* 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 <matthiasc@poet.de>
+
+ * 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 <matthiasc@poet.de>
* glib/tmpl/conversions.sgml: Update.
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.
</para>
<para>
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
(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)
</para>
<para>
The #GAsyncQueue struct is an opaque data structure, which represents
an asynchronous queue. It should only be accessed through the
-g_async_queue_* functions.
+<function>g_async_queue_*</function> functions.
</para>
<!-- ##### FUNCTION g_cache_destroy ##### -->
<para>
-Frees the memory allocated for the GCache.
+Frees the memory allocated for the #GCache.
</para>
<para>
Note that it does not destroy the keys and values which were contained in the
-GCache.
+#GCache.
</para>
@cache: a #GCache.
When no longer needed, the #GCompletion is freed with g_completion_free().
</para>
<para>
-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.
<!-- ##### MACRO G_HOOK_FLAG_USER_SHIFT ##### -->
<para>
-
+The position of the first bit which is not reserved for internal
+use be the #GHook implementation, i.e.
+<literal>1 << G_HOOK_FLAG_USER_SHIFT</literal> is the first bit
+which can be used for application-defined flags.
</para>
g_module_error().
</para>
<para>
-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).
</para>
<para>
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.
</para>
<para>
-For example, calling g_module_build_path() on a Linux system with a directory
-of <filename>/lib</filename> and a module_name of "mylibrary" will return <filename>/lib/libmylibrary.so</filename>.
-On a Windows system, using <filename>\Windows</filename> as the directory it will return
+For example, calling g_module_build_path() on a Linux system with a @directory
+of <filename>/lib</filename> and a @module_name of "mylibrary" will return
+<filename>/lib/libmylibrary.so</filename>. On a Windows system, using
+<filename>\Windows</filename> as the directory it will return
<filename>\Windows\mylibrary.dll</filename>.
</para>
@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.
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
Gets a symbol pointer from a module.
</para>
-@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.
<!-- ##### FUNCTION g_module_name ##### -->
<para>
-Gets the file name from a #GModule.
+Gets the filename from a #GModule.
</para>
-@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.
Any future g_module_close() calls on the module will be ignored.
</para>
-@module: a module to make permanently resident.
+@module: a #GModule to make permanently resident.
<!-- ##### FUNCTION g_module_close ##### -->
Closes a module.
</para>
-@module: the module to close.
+@module: a #GModule to close.
@Returns: %TRUE on success.
It is passed the #GModule structure.
</para>
-@module: the module about to be unloaded.
+@module: the #GModule about to be unloaded.
<!-- ##### MACRO G_MODULE_SUFFIX ##### -->
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: <ulink url="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</ulink>
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
-http://twister.ou.edu/workshop.docs/common-tools/numerical_comp_guide/ncg_math.doc.html
+<ulink url="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</ulink>
</para>
<!-- ##### MACRO G_IEEE754_FLOAT_BIAS ##### -->
<para>
-See http://twister.ou.edu/workshop.docs/common-tools/numerical_comp_guide/ncg_math.doc.html
+See <ulink url="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</ulink>
</para>
<!-- ##### MACRO G_IEEE754_DOUBLE_BIAS ##### -->
<para>
-See http://twister.ou.edu/workshop.docs/common-tools/numerical_comp_guide/ncg_math.doc.html
+See <ulink url="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</ulink>
</para>
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:
+<ulink url="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</ulink>
</para>
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:
+<ulink url="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</ulink>
</para>
<!-- ##### MACRO G_LOG_2_BASE_10 ##### -->
<para>
-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
+<ulink url="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</ulink>
</para>
<!-- ##### SECTION Long_Description ##### -->
<para>
-The <function>g_pattern_match*</function> match a string against
-a pattern containing '*' and '?' wildcards with similar semantics
+The <function>g_pattern_match*</function> functions match a string
+against a pattern containing '*' and '?' wildcards with similar semantics
as the standard <function>glob()</function> function: '*' matches an
arbitrary, possibly empty, string, '?' matches an arbitrary character.
+Note that in contrast to <function>glob()</function>, the '/' character
+<emphasis>can</emphasis> be matched by the wildcards.
</para>
<para>
There is no way to include literal '*' or '?' characters in a pattern.
</para>
<para>
-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
+<function>g_random_*</function> functions, which will create a globally
+used #GRand and use the according <function>g_rand_*</function> functions
+internally. Whenever you need a stream of reproducible random numbers, you
+better create a #GRand yourself and use the <funcion>g_rand_*</function>
+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.
</para>
<para>
-The g_rand*_range functions will return high quality equally
-distributed random numbers, whereas for example the
+The <function>g_rand*_range</function> functions will return high quality
+equally distributed random numbers, whereas for example the
<literal>(g_random_int()%%max)</literal> approach often doesn't
yield equally distributed numbers.
</para>
<!-- ##### STRUCT GRand ##### -->
<para>
The #GRand struct is an opaque data structure. It should only be
-accessed through the g_rand_* functions.
+accessed through the <function>g_rand_*</function> functions.
</para>
<!-- ##### MACRO g_rand_boolean ##### -->
<para>
-Return a random #gboolean from @rand. This corresponds to a unbiased
+Returns a random #gboolean from @rand. This corresponds to a unbiased
coin toss.
</para>
@begin:
@end:
@Returns:
-<!-- # Unused Parameters # -->
-@min:
-@max:
<!-- ##### FUNCTION g_rand_double ##### -->
@begin:
@end:
@Returns:
-<!-- # Unused Parameters # -->
-@min:
-@max:
<!-- ##### FUNCTION g_random_set_seed ##### -->
<!-- ##### MACRO g_random_boolean ##### -->
<para>
-Return a random #gboolean. This corresponds to a unbiased coin toss.
+Returns a random #gboolean. This corresponds to a unbiased coin toss.
</para>
@Returns: a random #gboolean.
@begin:
@end:
@Returns:
-<!-- # Unused Parameters # -->
-@min:
-@max:
<!-- ##### FUNCTION g_random_double ##### -->
@begin:
@end:
@Returns:
-<!-- # Unused Parameters # -->
-@min:
-@max:
@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.
-<!-- # Unused Parameters # -->
-@key_compare_func:
<!-- ##### FUNCTION g_relation_insert ##### -->
<!-- ##### FUNCTION g_relation_exists ##### -->
<para>
-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.
</para>
@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.
<!-- ##### FUNCTION g_relation_count ##### -->
<!-- ##### FUNCTION g_relation_delete ##### -->
<para>
-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.
</para>
To access the matched records, you must use g_tuples_index().
</para>
-@len:
+@len: the number of records that matched.
<!-- ##### FUNCTION g_tuples_destroy ##### -->
<para>
Trash Stacks
<!-- ##### SECTION Short_Description ##### -->
-
+maintain a stack of unused allocated memory chunks.
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+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.
+</para>
+<para>
+There is no function to create a #GTrashStack. A %NULL #GTrashStack*
+is a perfectly valid empty stack.
</para>
<!-- ##### SECTION See_Also ##### -->
<!-- ##### STRUCT GTrashStack ##### -->
<para>
-
+Each piece of memory that is pushed onto the stack
+is cast to a <structname>GTrashStack*</structname>.
</para>
-@next:
+@next: pointer to the previous element of the stack,
+gets stored in the first <literal>sizeof (gpointer)</literal>
+bytes of the element.
<!-- ##### FUNCTION g_trash_stack_push ##### -->
<para>
-
+Pushes a piece of memory onto a #GTrashStack.
</para>
-@stack_p:
-@data_p:
+@stack_p: a pointer to a #GTrashStack.
+@data_p: the piece of memory to push on the stack.
<!-- ##### FUNCTION g_trash_stack_pop ##### -->
<para>
-
+Pops a piece of memory off a #GTrashStack.
</para>
-@stack_p:
-@Returns:
+@stack_p: a pointer to a #GTrashStack.
+@Returns: the element at the top of the stack.
<!-- ##### FUNCTION g_trash_stack_peek ##### -->
<para>
-
+Returns the element at the top of a #GTrashStack.
</para>
-@stack_p:
-@Returns:
+@stack_p: a pointer to a #GTrashStack.
+@Returns: the element at the top of the stack.
<!-- ##### FUNCTION g_trash_stack_height ##### -->
<para>
-
+Returns the height of a #GTrashStack.
</para>
-@stack_p:
-@Returns:
+@stack_p: a pointer to a #GTrashStack.
+@Returns: the height of the stack.
projects / platform / upstream / glib.git / commitdiff