From fc0ed5b29de987ec5370ba3cbb680c08e6f94a0c Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Fri, 5 Oct 2001 20:53:02 +0000 Subject: [PATCH] Document G_HOOK_FLAG_USER_SHIFT. * glib/tmpl/hooks.sgml: Document G_HOOK_FLAG_USER_SHIFT. * glib/tmpl/trash_stacks.sgml: Document trash stacks. * glib/tmpl/async_queues.sgml, glib/tmpl/caches.sgml, glib/tmpl/completion.sgml, glib/tmpl/patterns.sgml, glib/tmpl/numerical.sgml, glib/tmpl/random_numbers.sgml, glib/tmpl/relations.sgml, glib/tmpl/modules.sgml: Update. --- docs/reference/ChangeLog | 11 ++++++++ docs/reference/glib/tmpl/async_queues.sgml | 10 +++---- docs/reference/glib/tmpl/caches.sgml | 4 +-- docs/reference/glib/tmpl/completion.sgml | 2 +- docs/reference/glib/tmpl/hooks.sgml | 5 +++- docs/reference/glib/tmpl/modules.sgml | 31 ++++++++++---------- docs/reference/glib/tmpl/numerical.sgml | 17 ++++++----- docs/reference/glib/tmpl/patterns.sgml | 6 ++-- docs/reference/glib/tmpl/random_numbers.sgml | 38 +++++++++---------------- docs/reference/glib/tmpl/relations.sgml | 10 +++---- docs/reference/glib/tmpl/trash_stack.sgml | 42 +++++++++++++++++----------- 11 files changed, 96 insertions(+), 80 deletions(-) diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index e3f85ab..e9df56c 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,4 +1,15 @@ 2001-10-05 Matthias Clasen + + * glib/tmpl/hooks.sgml: Document G_HOOK_FLAG_USER_SHIFT. + + * glib/tmpl/trash_stacks.sgml: Document trash stacks. + + * glib/tmpl/async_queues.sgml, glib/tmpl/caches.sgml, + glib/tmpl/completion.sgml, glib/tmpl/patterns.sgml, + glib/tmpl/numerical.sgml, glib/tmpl/random_numbers.sgml, + glib/tmpl/relations.sgml, glib/tmpl/modules.sgml: Update. + +2001-10-05 Matthias Clasen * glib/tmpl/conversions.sgml: Update. diff --git a/docs/reference/glib/tmpl/async_queues.sgml b/docs/reference/glib/tmpl/async_queues.sgml index 7a991cc..e5220a1 100644 --- a/docs/reference/glib/tmpl/async_queues.sgml +++ b/docs/reference/glib/tmpl/async_queues.sgml @@ -17,15 +17,15 @@ well be done in the same thread. Asynchronous queues are an exception from most other GLib data structures, as they can be used simultaneously from multiple threads without explicit locking and they bring their own builtin reference -counting. This is because the nature of an asynchronous queue is, that +counting. This is because the nature of an asynchronous queue is that it will always be used by at least 2 concurrent threads. For using an asynchronous queue you first have to create one with -g_async_queue_new(). A newly created queue will get the reference +g_async_queue_new(). A newly-created queue will get the reference count 1. Whenever another thread is creating a new reference of (that -is pointer to) the queue, it has to increase the reference count +is, pointer to) the queue, it has to increase the reference count (using g_async_queue_ref()). Also, before removing this reference, the reference count has to be decreased (using g_async_queue_unref()). After that the queue might no longer exist so @@ -53,7 +53,7 @@ queue and one that doesn't. That way you can hold the queue lock (acquire it with g_async_queue_lock() and release it with g_async_queue_unlock()) over multiple queue accessing instructions. This can be necessary to ensure the integrity of the -queue, but should only be used, when really necessary as it can make +queue, but should only be used when really necessary, as it can make your life harder if used unwisely. Normally you should only use the locking function variants (those without the suffix _unlocked) @@ -67,7 +67,7 @@ locking function variants (those without the suffix _unlocked) The #GAsyncQueue struct is an opaque data structure, which represents an asynchronous queue. It should only be accessed through the -g_async_queue_* functions. +g_async_queue_* functions. diff --git a/docs/reference/glib/tmpl/caches.sgml b/docs/reference/glib/tmpl/caches.sgml index 268859d..887d467 100644 --- a/docs/reference/glib/tmpl/caches.sgml +++ b/docs/reference/glib/tmpl/caches.sgml @@ -87,11 +87,11 @@ using the @value_destroy_func and @key_destroy_func passed to g_cache_new(). -Frees the memory allocated for the GCache. +Frees the memory allocated for the #GCache. Note that it does not destroy the keys and values which were contained in the -GCache. +#GCache. @cache: a #GCache. diff --git a/docs/reference/glib/tmpl/completion.sgml b/docs/reference/glib/tmpl/completion.sgml index f91b65c..24d6e91 100644 --- a/docs/reference/glib/tmpl/completion.sgml +++ b/docs/reference/glib/tmpl/completion.sgml @@ -19,7 +19,7 @@ A completion attempt is requested with g_completion_complete(). When no longer needed, the #GCompletion is freed with g_completion_free(). -Items in the completion can be simple strings (e.g. file names), +Items in the completion can be simple strings (e.g. filenames), or pointers to arbitrary data structures. If data structures are used you must provide a #GCompletionFunc in g_completion_new(), which retrieves the item's string from the data structure. diff --git a/docs/reference/glib/tmpl/hooks.sgml b/docs/reference/glib/tmpl/hooks.sgml index 7762b33..35d804f 100644 --- a/docs/reference/glib/tmpl/hooks.sgml +++ b/docs/reference/glib/tmpl/hooks.sgml @@ -435,7 +435,10 @@ Returns the flags of a hook. - +The position of the first bit which is not reserved for internal +use be the #GHook implementation, i.e. +1 << G_HOOK_FLAG_USER_SHIFT is the first bit +which can be used for application-defined flags. diff --git a/docs/reference/glib/tmpl/modules.sgml b/docs/reference/glib/tmpl/modules.sgml index f301201..a3b1d3a 100644 --- a/docs/reference/glib/tmpl/modules.sgml +++ b/docs/reference/glib/tmpl/modules.sgml @@ -31,7 +31,7 @@ If any of the above functions fail, the error status can be found with g_module_error(). -The gmodule implementation features reference counting for opened modules, +The #GModule implementation features reference counting for opened modules, and supports hook functions within a module which are called when the module is loaded and unloaded (see #GModuleCheckInit and #GModuleUnload). @@ -71,19 +71,20 @@ added to the directory, using the correct separator character. The directory should specify the directory where the module can be found. It can be %NULL or an empty string to indicate that the module is in a standard -operating-system specific directory, though this is not recommended since the +platform-specific directory, though this is not recommended since the wrong module may be found. -For example, calling g_module_build_path() on a Linux system with a directory -of /lib and a module_name of "mylibrary" will return /lib/libmylibrary.so. -On a Windows system, using \Windows as the directory it will return +For example, calling g_module_build_path() on a Linux system with a @directory +of /lib and a @module_name of "mylibrary" will return +/lib/libmylibrary.so. On a Windows system, using +\Windows as the directory it will return \Windows\mylibrary.dll. @directory: the directory where the module is. This can be %NULL or the empty -string to indicate that the standard operating system-specific directories -will be used, though that is not recommended. +string to indicate that the standard platform-specific directories will be +used, though that is not recommended. @module_name: the name of the module. @Returns: the complete path of the module, including the standard library prefix and suffix. This should be freed when no longer needed. @@ -99,7 +100,7 @@ count is incremented. First of all g_module_open() tries to open @file_name as a module. If that fails and @file_name has the ".la"-suffix (and is a libtool archive) it tries to open the corresponding module. If that fails and it doesn't -have the proper module suffix for that platform (#G_MODULE_SUFFIX), this +have the proper module suffix for the platform (#G_MODULE_SUFFIX), this suffix will be appended and the corresponding module will be opended. If that fails and @file_name doesn't have the ".la"-suffix, this suffix is appended and g_module_open() tries to open the corresponding module. If @@ -128,7 +129,7 @@ The default action is to bind all symbols when the module is loaded. Gets a symbol pointer from a module. -@module: the module. +@module: a #GModule. @symbol_name: the name of the symbol to find. @symbol: returns the pointer to the symbol value. @Returns: %TRUE on success. @@ -136,11 +137,11 @@ Gets a symbol pointer from a module. -Gets the file name from a #GModule. +Gets the filename from a #GModule. -@module: the module. -@Returns: the file name of the module, or "main" if the module is the main +@module: a #GModule. +@Returns: the filename of the module, or "main" if the module is the main program itself. @@ -150,7 +151,7 @@ Ensures that a module will never be unloaded. Any future g_module_close() calls on the module will be ignored. -@module: a module to make permanently resident. +@module: a #GModule to make permanently resident. @@ -158,7 +159,7 @@ Any future g_module_close() calls on the module will be ignored. Closes a module. -@module: the module to close. +@module: a #GModule to close. @Returns: %TRUE on success. @@ -191,7 +192,7 @@ automatically when the module is unloaded. It is passed the #GModule structure. -@module: the module about to be unloaded. +@module: the #GModule about to be unloaded. diff --git a/docs/reference/glib/tmpl/numerical.sgml b/docs/reference/glib/tmpl/numerical.sgml index d23bbb9..661a3ba 100644 --- a/docs/reference/glib/tmpl/numerical.sgml +++ b/docs/reference/glib/tmpl/numerical.sgml @@ -17,24 +17,24 @@ The #GFloatIEEE754 and #GDoubleIEEE754 unions are used to access the sign, mantissa and exponent of IEEE floats and doubles. These unions are defined as appropriate for a given platform. IEEE floats and doubles are supported (used for - storage) by at least intel, ppc and sparc, for reference: http://twister.ou.edu/workshop.docs/common-tools/numerical_comp_guide/ncg_math.doc.html + storage) by at least intel, ppc and sparc, for reference: http://twister.ou.edu/workshop.docs/common-tools/numerical_comp_guide/ncg_math.doc.html -http://twister.ou.edu/workshop.docs/common-tools/numerical_comp_guide/ncg_math.doc.html +http://twister.ou.edu/workshop.docs/common-tools/numerical_comp_guide/ncg_math.doc.html -See http://twister.ou.edu/workshop.docs/common-tools/numerical_comp_guide/ncg_math.doc.html +See http://twister.ou.edu/workshop.docs/common-tools/numerical_comp_guide/ncg_math.doc.html -See http://twister.ou.edu/workshop.docs/common-tools/numerical_comp_guide/ncg_math.doc.html +See http://twister.ou.edu/workshop.docs/common-tools/numerical_comp_guide/ncg_math.doc.html @@ -45,7 +45,8 @@ The #GFloatIEEE754 and #GDoubleIEEE754 unions are used to access the sign, mantissa and exponent of IEEE floats and doubles. These unions are defined as appropriate for a given platform. IEEE floats and doubles are supported (used for - storage) by at least intel, ppc and sparc, for reference: http://twister.ou.edu/workshop.docs/common-tools/numerical_comp_guide/ncg_math.doc.html + storage) by at least intel, ppc and sparc, for reference: +http://twister.ou.edu/workshop.docs/common-tools/numerical_comp_guide/ncg_math.doc.html @@ -55,7 +56,8 @@ The #GFloatIEEE754 and #GDoubleIEEE754 unions are used to access the sign, mantissa and exponent of IEEE floats and doubles. These unions are defined as appropriate for a given platform. IEEE floats and doubles are supported (used for - storage) by at least intel, ppc and sparc, for reference: http://twister.ou.edu/workshop.docs/common-tools/numerical_comp_guide/ncg_math.doc.html + storage) by at least intel, ppc and sparc, for reference: +http://twister.ou.edu/workshop.docs/common-tools/numerical_comp_guide/ncg_math.doc.html @@ -110,7 +112,8 @@ The square root of two. -Used for fooling around with float formats, see http://twister.ou.edu/workshop.docs/common-tools/numerical_comp_guide/ncg_math.doc.html +Used for fooling around with float formats, see +http://twister.ou.edu/workshop.docs/common-tools/numerical_comp_guide/ncg_math.doc.html diff --git a/docs/reference/glib/tmpl/patterns.sgml b/docs/reference/glib/tmpl/patterns.sgml index caae8ce..cfea474 100644 --- a/docs/reference/glib/tmpl/patterns.sgml +++ b/docs/reference/glib/tmpl/patterns.sgml @@ -7,10 +7,12 @@ Matches strings against patterns containing '*' and '?' wildcards. -The g_pattern_match* match a string against -a pattern containing '*' and '?' wildcards with similar semantics +The g_pattern_match* functions match a string +against a pattern containing '*' and '?' wildcards with similar semantics as the standard glob() function: '*' matches an arbitrary, possibly empty, string, '?' matches an arbitrary character. +Note that in contrast to glob(), the '/' character +can be matched by the wildcards. There is no way to include literal '*' or '?' characters in a pattern. diff --git a/docs/reference/glib/tmpl/random_numbers.sgml b/docs/reference/glib/tmpl/random_numbers.sgml index 745ac8f..88d6716 100644 --- a/docs/reference/glib/tmpl/random_numbers.sgml +++ b/docs/reference/glib/tmpl/random_numbers.sgml @@ -15,19 +15,19 @@ url="http://www.math.keio.ac.jp/~matumoto/emt.html" -If you just need a random number, you simply call the g_random_* -functions, which will create a globally used #GRand and use the -according g_rand_* function internally. Whenever you need a stream of -reproducible random numbers, you better create a #GRand yourself and -use the g_rand_* functions directly, which will also be slightly -faster. Initializing a GRand with a certain seed will produce exactly -the same series of random numbers on all platforms. This can thus be -used as a seed for e.g. games. +If you just need a random number, you simply call the +g_random_* functions, which will create a globally +used #GRand and use the according g_rand_* functions +internally. Whenever you need a stream of reproducible random numbers, you +better create a #GRand yourself and use the g_rand_* +functions directly, which will also be slightly faster. Initializing a #GRand +with a certain seed will produce exactly the same series of random numbers +on all platforms. This can thus be used as a seed for e.g. games. -The g_rand*_range functions will return high quality equally -distributed random numbers, whereas for example the +The g_rand*_range functions will return high quality +equally distributed random numbers, whereas for example the (g_random_int()%%max) approach often doesn't yield equally distributed numbers. @@ -40,7 +40,7 @@ yield equally distributed numbers. The #GRand struct is an opaque data structure. It should only be -accessed through the g_rand_* functions. +accessed through the g_rand_* functions. @@ -72,7 +72,7 @@ accessed through the g_rand_* functions. -Return a random #gboolean from @rand. This corresponds to a unbiased +Returns a random #gboolean from @rand. This corresponds to a unbiased coin toss. @@ -94,9 +94,6 @@ coin toss. @begin: @end: @Returns: - -@min: -@max: @@ -113,9 +110,6 @@ coin toss. @begin: @end: @Returns: - -@min: -@max: @@ -126,7 +120,7 @@ coin toss. -Return a random #gboolean. This corresponds to a unbiased coin toss. +Returns a random #gboolean. This corresponds to a unbiased coin toss. @Returns: a random #gboolean. @@ -144,9 +138,6 @@ Return a random #gboolean. This corresponds to a unbiased coin toss. @begin: @end: @Returns: - -@min: -@max: @@ -161,8 +152,5 @@ Return a random #gboolean. This corresponds to a unbiased coin toss. @begin: @end: @Returns: - -@min: -@max: diff --git a/docs/reference/glib/tmpl/relations.sgml b/docs/reference/glib/tmpl/relations.sgml index 5e83181..70b7ce6 100644 --- a/docs/reference/glib/tmpl/relations.sgml +++ b/docs/reference/glib/tmpl/relations.sgml @@ -84,8 +84,6 @@ Note that this must be called before any records are added to the #GRelation. @field: the field to index, counting from 0. @hash_func: a function to produce a hash value from the field data. @key_equal_func: a function to compare two values of the given field. - -@key_compare_func: @@ -100,7 +98,7 @@ fields in the #GRelation. -Returns TRUE if a record with the given values exists in a #GRelation. +Returns %TRUE if a record with the given values exists in a #GRelation. Note that the values are compared directly, so that, for example, two copies of the same string will not match. @@ -108,7 +106,7 @@ copies of the same string will not match. @relation: a #GRelation. @Varargs: the fields of the record to compare. The number must match the number of fields in the #GRelation. -@Returns: TRUE if a record matches. +@Returns: %TRUE if a record matches. @@ -138,7 +136,7 @@ The returned records should be freed with g_tuples_destroy(). -Deletes any records from a GRelation that have the given key value in +Deletes any records from a #GRelation that have the given key value in the given field. @@ -175,7 +173,7 @@ It only contains one public member - the number of records that matched. To access the matched records, you must use g_tuples_index(). -@len: +@len: the number of records that matched. diff --git a/docs/reference/glib/tmpl/trash_stack.sgml b/docs/reference/glib/tmpl/trash_stack.sgml index 2d28613..e496c6b 100644 --- a/docs/reference/glib/tmpl/trash_stack.sgml +++ b/docs/reference/glib/tmpl/trash_stack.sgml @@ -2,11 +2,18 @@ Trash Stacks - +maintain a stack of unused allocated memory chunks. - +A #GTrashStack is an efficient way to keep a stack of unused allocated +memory chunks. Each memory chunk is required to be large enough to hold +a #gpointer. This allows the stack to be maintained without any space +overhead, since the stack pointers can be stored inside the memory chunks. + + +There is no function to create a #GTrashStack. A %NULL #GTrashStack* +is a perfectly valid empty stack. @@ -16,44 +23,47 @@ Trash Stacks - +Each piece of memory that is pushed onto the stack +is cast to a GTrashStack*. -@next: +@next: pointer to the previous element of the stack, +gets stored in the first sizeof (gpointer) +bytes of the element. - +Pushes a piece of memory onto a #GTrashStack. -@stack_p: -@data_p: +@stack_p: a pointer to a #GTrashStack. +@data_p: the piece of memory to push on the stack. - +Pops a piece of memory off a #GTrashStack. -@stack_p: -@Returns: +@stack_p: a pointer to a #GTrashStack. +@Returns: the element at the top of the stack. - +Returns the element at the top of a #GTrashStack. -@stack_p: -@Returns: +@stack_p: a pointer to a #GTrashStack. +@Returns: the element at the top of the stack. - +Returns the height of a #GTrashStack. -@stack_p: -@Returns: +@stack_p: a pointer to a #GTrashStack. +@Returns: the height of the stack. -- 2.7.4