luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-01-12 15:36:17 +01:00
Code Issues Packages Projects Releases Wiki Activity

Document G_HOOK_FLAG_USER_SHIFT.

Browse Source 
* 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.
This commit is contained in:
Matthias Clasen 2001-10-05 20:53:02 +00:00
parent 8cf85caa46
commit fc0ed5b29d
11 changed files with 96 additions and 80 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
docs/reference/ChangeLog
View File

@ -1,3 +1,14 @@
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.

10
docs/reference/glib/tmpl/async_queues.sgml
View File

@ -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.
</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
@ -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)
</para>
@ -67,7 +67,7 @@ locking function variants (those without the suffix _unlocked)
<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>

4
docs/reference/glib/tmpl/caches.sgml
View File

@ -87,11 +87,11 @@ using the @value_destroy_func and @key_destroy_func passed to g_cache_new().
<!-- ##### 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.

2
docs/reference/glib/tmpl/completion.sgml
View File

@ -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().
</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.

5
docs/reference/glib/tmpl/hooks.sgml
View File

@ -435,7 +435,10 @@ Returns the flags of a hook.
<!-- ##### 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>

31
docs/reference/glib/tmpl/modules.sgml
View File

@ -31,7 +31,7 @@ If any of the above functions fail, the error status can be found with
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>
@ -71,19 +71,20 @@ added to the directory, using the correct separator character.
<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.
@ -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.
</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.
@ -136,11 +137,11 @@ Gets a symbol pointer from a module.
<!-- ##### 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.
@ -150,7 +151,7 @@ Ensures that a module will never be unloaded.
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 ##### -->
@ -158,7 +159,7 @@ Any future g_module_close() calls on the module will be ignored.
Closes a module.
</para>
@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.
</para>
@module: the module about to be unloaded.
@module: the #GModule about to be unloaded.
<!-- ##### MACRO G_MODULE_SUFFIX ##### -->

17
docs/reference/glib/tmpl/numerical.sgml
View File

@ -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: <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>
@ -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:
<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>
@ -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:
<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>
@ -110,7 +112,8 @@ The square root of two.
<!-- ##### 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>

6
docs/reference/glib/tmpl/patterns.sgml
View File

@ -7,10 +7,12 @@ Matches strings against patterns containing '*' and '?' wildcards.
<!-- ##### 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.

38
docs/reference/glib/tmpl/random_numbers.sgml
View File

@ -15,19 +15,19 @@ url="http://www.math.keio.ac.jp/~matumoto/emt.html"
</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>
@ -40,7 +40,7 @@ yield equally distributed numbers.
<!-- ##### 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>
@ -72,7 +72,7 @@ accessed through the g_rand_* functions.
<!-- ##### 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>
@ -94,9 +94,6 @@ coin toss.
@begin:
@end:
@Returns:
<!-- # Unused Parameters # -->
@min:
@max:
<!-- ##### FUNCTION g_rand_double ##### -->
@ -113,9 +110,6 @@ coin toss.
@begin:
@end:
@Returns:
<!-- # Unused Parameters # -->
@min:
@max:
<!-- ##### FUNCTION g_random_set_seed ##### -->
@ -126,7 +120,7 @@ coin toss.
<!-- ##### 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.
@ -144,9 +138,6 @@ Return a random #gboolean. This corresponds to a unbiased coin toss.
@begin:
@end:
@Returns:
<!-- # Unused Parameters # -->
@min:
@max:
<!-- ##### FUNCTION g_random_double ##### -->
@ -161,8 +152,5 @@ Return a random #gboolean. This corresponds to a unbiased coin toss.
@begin:
@end:
@Returns:
<!-- # Unused Parameters # -->
@min:
@max:

10
docs/reference/glib/tmpl/relations.sgml
View File

@ -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.
<!-- # Unused Parameters # -->
@key_compare_func:
<!-- ##### FUNCTION g_relation_insert ##### -->
@ -100,7 +98,7 @@ fields in the #GRelation.
<!-- ##### 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>
@ -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.
<!-- ##### FUNCTION g_relation_count ##### -->
@ -138,7 +136,7 @@ The returned records should be freed with g_tuples_destroy().
<!-- ##### 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>
@ -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().
</para>
@len:
@len: the number of records that matched.
<!-- ##### FUNCTION g_tuples_destroy ##### -->
<para>

42
docs/reference/glib/tmpl/trash_stack.sgml
View File

@ -2,11 +2,18 @@
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 ##### -->
@ -16,44 +23,47 @@ Trash Stacks
<!-- ##### 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.