From f3eac349f9bb04e02cb33da4e5487f83225e25c1 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Mon, 25 Sep 2023 14:20:37 -0400 Subject: [PATCH] docs: Move the GType SECTION Move the contents to the new types.md files. Helps: #3037 --- docs/reference/gobject/gobject.toml.in | 1 + docs/reference/gobject/meson.build | 1 + docs/reference/gobject/types.md | 64 ++++++++++++++++++++++++++ gobject/gtype.c | 59 ------------------------ 4 files changed, 66 insertions(+), 59 deletions(-) create mode 100644 docs/reference/gobject/types.md diff --git a/docs/reference/gobject/gobject.toml.in b/docs/reference/gobject/gobject.toml.in index 881971449..75421e8e1 100644 --- a/docs/reference/gobject/gobject.toml.in +++ b/docs/reference/gobject/gobject.toml.in @@ -44,6 +44,7 @@ urlmap_file = "urlmap.js" content_files = [ "concepts.md", "tutorial.md", + "types.md", "floating-refs.md", "boxed.md", "enum-types.md", diff --git a/docs/reference/gobject/meson.build b/docs/reference/gobject/meson.build index 3a608ddfe..092cb0a12 100644 --- a/docs/reference/gobject/meson.build +++ b/docs/reference/gobject/meson.build @@ -72,6 +72,7 @@ expand_content_files = [ 'floating-refs.md', 'gvalue.md', 'tutorial.md', + 'types.md', ] gobject_gir = meson.current_source_dir() / 'GObject-2.0.gir' diff --git a/docs/reference/gobject/types.md b/docs/reference/gobject/types.md new file mode 100644 index 000000000..8b9bc5d21 --- /dev/null +++ b/docs/reference/gobject/types.md @@ -0,0 +1,64 @@ +Title: Types +SPDX-License-Identifier: LGPL-2.1-or-later +SPDX-FileCopyrightText: 2001, 2003 Owen Taylor +SPDX-FileCopyrightText: 2002, 2003, 2004, 2005 Matthias Clasen +SPDX-FileCopyrightText: 2003, 2006 Josh Parsons +SPDX-FileCopyrightText: 2005 Stefan Kost +SPDX-FileCopyrightText: 2015 Collabora, Ltd. +SPDX-FileCopyrightText: 2021 Emmanuele Bassi +SPDX-FileCopyrightText: 2023 Endless OS Foundation, LLC + +# Types + +The GType API is the foundation of the GObject system. It provides the +facilities for registering and managing all fundamental data types, +user-defined object and interface types. + +For type creation and registration purposes, all types fall into one of +two categories: static or dynamic. Static types are never loaded or +unloaded at run-time as dynamic types may be. Static types are created +with [func@GObject.type_register_static] that gets type specific +information passed in via a `GTypeInfo` structure. + +Dynamic types are created with [func@GObject.type_register_dynamic], +which takes a `GTypePlugin` structure instead. The remaining type information +(the `GTypeInfo` structure) is retrieved during runtime through `GTypePlugin` +and the `g_type_plugin_*()` API. + +These registration functions are usually called only once from a +function whose only purpose is to return the type identifier for a +specific class. Once the type (or class or interface) is registered, +it may be instantiated, inherited, or implemented depending on exactly +what sort of type it is. + +There is also a third registration function for registering fundamental +types called [func@GObject.type_register_fundamental], which requires +both a `GTypeInfo` structure and a `GTypeFundamentalInfo` structure, but it +is rarely used since most fundamental types are predefined rather than user-defined. + +Type instance and class structs are limited to a total of 64 KiB, +including all parent types. Similarly, type instances' private data +(as created by `G_ADD_PRIVATE()`) are limited to a total of +64 KiB. If a type instance needs a large static buffer, allocate it +separately (typically by using [`struct@GLib.Array`] or [`struct@GLib.PtrArray`]) +and put a pointer to the buffer in the structure. + +As mentioned in the [GType conventions](concepts.html#conventions), type names must +be at least three characters long. There is no upper length limit. The first +character must be a letter (a–z or A–Z) or an underscore (‘\_’). Subsequent +characters can be letters, numbers or any of ‘-\_+’. + +# Runtime Debugging + +When `G_ENABLE_DEBUG` is defined during compilation, the GObject library +supports an environment variable `GOBJECT_DEBUG` that can be set to a +combination of flags to trigger debugging messages about +object bookkeeping and signal emissions during runtime. + +The currently supported flags are: + + - `objects`: Tracks all `GObject` instances in a global hash table called + `debug_objects_ht`, and prints the still-alive objects on exit. + - `instance-count`: Tracks the number of instances of every `GType` and makes + it available via the [func@GObject.type_get_instance_count] function. + - `signals`: Currently unused. diff --git a/gobject/gtype.c b/gobject/gtype.c index 371e94cd6..ee936b544 100644 --- a/gobject/gtype.c +++ b/gobject/gtype.c @@ -44,65 +44,6 @@ #define IF_DEBUG(debug_type) if (_g_type_debug_flags & G_TYPE_DEBUG_ ## debug_type) #endif -/** - * SECTION:gtype - * @short_description: The GLib Runtime type identification and - * management system - * @title:Type Information - * - * The GType API is the foundation of the GObject system. It provides the - * facilities for registering and managing all fundamental data types, - * user-defined object and interface types. - * - * For type creation and registration purposes, all types fall into one of - * two categories: static or dynamic. Static types are never loaded or - * unloaded at run-time as dynamic types may be. Static types are created - * with g_type_register_static() that gets type specific information passed - * in via a #GTypeInfo structure. - * - * Dynamic types are created with g_type_register_dynamic() which takes a - * #GTypePlugin structure instead. The remaining type information (the - * #GTypeInfo structure) is retrieved during runtime through #GTypePlugin - * and the g_type_plugin_*() API. - * - * These registration functions are usually called only once from a - * function whose only purpose is to return the type identifier for a - * specific class. Once the type (or class or interface) is registered, - * it may be instantiated, inherited, or implemented depending on exactly - * what sort of type it is. - * - * There is also a third registration function for registering fundamental - * types called g_type_register_fundamental() which requires both a #GTypeInfo - * structure and a #GTypeFundamentalInfo structure but it is seldom used - * since most fundamental types are predefined rather than user-defined. - * - * Type instance and class structs are limited to a total of 64 KiB, - * including all parent types. Similarly, type instances' private data - * (as created by G_ADD_PRIVATE()) are limited to a total of - * 64 KiB. If a type instance needs a large static buffer, allocate it - * separately (typically by using #GArray or #GPtrArray) and put a pointer - * to the buffer in the structure. - * - * As mentioned in the [GType conventions][gtype-conventions], type names must - * be at least three characters long. There is no upper length limit. The first - * character must be a letter (a–z or A–Z) or an underscore (‘_’). Subsequent - * characters can be letters, numbers or any of ‘-_+’. - * - * # Runtime Debugging - * - * When `G_ENABLE_DEBUG` is defined during compilation, the GObject library - * supports an environment variable `GOBJECT_DEBUG` that can be set to a - * combination of flags to trigger debugging messages about - * object bookkeeping and signal emissions during runtime. - * - * The currently supported flags are: - * - `objects`: Tracks all #GObject instances in a global hash table called - * `debug_objects_ht`, and prints the still-alive objects on exit. - * - `instance-count`: Tracks the number of instances of every #GType and makes - * it available via the g_type_get_instance_count() function. - * - `signals`: Currently unused. - */ - /* NOTE: some functions (some internal variants and exported ones) * invalidate data portions of the TypeNodes. if external functions/callbacks