mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2025-02-04 10:16:17 +01:00
copyediting API docs
This commit is contained in:
Josh Parsons
parent
2edf2f2571
commit
3d4e51759a
@ -1,3 +1,8 @@
|
||||
2006-08-10 Josh Parsons <josh.parsons@stonebow.otago.ac.nz>
|
||||
|
||||
* gobject/tmpl/gtype.sgml:
|
||||
* glib/tmpl/threads.sgml: Style and grammar fixes.
|
||||
|
||||
2006-08-05 Matthias Clasen <mclasen@redhat.com>
|
||||
|
||||
* glib/tmpl/messages.sgml: Add some hints
|
||||
|
||||
@ -13,11 +13,12 @@ and thread private data.
|
||||
Threads act almost like processes, but unlike processes all threads of
|
||||
one process share the same memory. This is good, as it provides easy
|
||||
communication between the involved threads via this shared memory, and
|
||||
it is bad, because strange things (so called Heisenbugs) might happen,
|
||||
when the program is not carefully designed. Especially bad is, that due
|
||||
to the concurrent nature of threads no assumptions on the order of
|
||||
execution of different threads can be done unless explicitly forced by
|
||||
the programmer through synchronization primitives.
|
||||
it is bad, because strange things (so called "Heisenbugs") might
|
||||
happen if the program is not carefully designed. In particular, due to
|
||||
the concurrent nature of threads, no assumptions on the order of
|
||||
execution of code running in different threads can be made, unless
|
||||
order is explicitly forced by the programmer through synchronization
|
||||
primitives.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
@ -25,21 +26,22 @@ The aim of the thread related functions in GLib is to provide a
|
||||
portable means for writing multi-threaded software. There are
|
||||
primitives for mutexes to protect the access to portions of memory
|
||||
(#GMutex, #GStaticMutex, #G_LOCK_DEFINE, #GStaticRecMutex and
|
||||
#GStaticRWLock), there are primitives for condition variables to allow
|
||||
synchronization of threads (#GCond) and finally there are primitives
|
||||
for thread-private data, that every thread has a private instance of
|
||||
#GStaticRWLock). There are primitives for condition variables to allow
|
||||
synchronization of threads (#GCond). There are primitives
|
||||
for thread-private data - data that every thread has a private instance of
|
||||
(#GPrivate, #GStaticPrivate). Last but definitely not least there are
|
||||
primitives to portably create and manage threads (#GThread).
|
||||
</para>
|
||||
|
||||
<para>
|
||||
You must call g_thread_init() before executing any other GLib functions
|
||||
in a threaded GLib program. After that, GLib is completely thread safe
|
||||
(all global data is automatically locked). But individual data structure
|
||||
instances are not automatically locked for performance reasons. So e.g.
|
||||
you must coordinate accesses to the same #GHashTable from multiple threads.
|
||||
The two notable exceptions from this rule are #GMainLoop and #GAsyncQueue,
|
||||
which <emphasis>are</emphasis> threadsafe and needs no further
|
||||
You must call g_thread_init() before executing any other GLib
|
||||
functions in a threaded GLib program. After that, GLib is completely
|
||||
thread safe (all global data is automatically locked), but individual
|
||||
data structure instances are not automatically locked for performance
|
||||
reasons. So, for example you must coordinate accesses to the same
|
||||
#GHashTable from multiple threads. The two notable exceptions from
|
||||
this rule are #GMainLoop and #GAsyncQueue,
|
||||
which <emphasis>are</emphasis> threadsafe and needs no further
|
||||
application-level locking to be accessed from multiple threads.
|
||||
</para>
|
||||
|
||||
@ -66,11 +68,12 @@ application-level locking to be accessed from multiple threads.
|
||||
<!-- ##### MACRO G_THREADS_ENABLED ##### -->
|
||||
|
||||
<para>
|
||||
This macro is defined, if GLib was compiled with thread support. This
|
||||
does not necessarily mean, that there is a thread implementation
|
||||
available, but the infrastructure is in place and once you provide a
|
||||
thread implementation to g_thread_init(), GLib will be multi-thread
|
||||
safe. It isn't and cannot be, if #G_THREADS_ENABLED is not defined.
|
||||
This macro is defined if GLib was compiled with thread support. This
|
||||
does not necessarily mean that there is a thread implementation
|
||||
available, but it does mean that the infrastructure is in place and
|
||||
that once you provide a thread implementation to g_thread_init(), GLib
|
||||
will be multi-thread safe. If #G_THREADS_ENABLED is not defined, then
|
||||
Glib is not, and cannot be, multi-thread safe.
|
||||
</para>
|
||||
|
||||
|
||||
@ -78,7 +81,7 @@ safe. It isn't and cannot be, if #G_THREADS_ENABLED is not defined.
|
||||
<!-- ##### MACRO G_THREADS_IMPL_POSIX ##### -->
|
||||
|
||||
<para>
|
||||
This macro is defined, if POSIX style threads are used.
|
||||
This macro is defined if POSIX style threads are used.
|
||||
</para>
|
||||
|
||||
|
||||
@ -86,8 +89,8 @@ This macro is defined, if POSIX style threads are used.
|
||||
<!-- ##### MACRO G_THREADS_IMPL_NONE ##### -->
|
||||
|
||||
<para>
|
||||
This macro is defined, if no thread implementation is used. You can
|
||||
however provide one to g_thread_init() to make GLib multi-thread safe.
|
||||
This macro is defined if no thread implementation is used. You can,
|
||||
however, provide one to g_thread_init() to make GLib multi-thread safe.
|
||||
</para>
|
||||
|
||||
|
||||
@ -111,15 +114,15 @@ shortage. Try again later.
|
||||
|
||||
<para>
|
||||
This function table is used by g_thread_init() to initialize the
|
||||
thread system. The functions in that table are directly used by their
|
||||
g_* prepended counterparts, that are described here, e.g. if you call
|
||||
g_mutex_new() then mutex_new() from the table provided to
|
||||
thread system. The functions in the table are directly used by their
|
||||
g_* prepended counterparts (described in this document). For example,
|
||||
if you call g_mutex_new() then mutex_new() from the table provided to
|
||||
g_thread_init() will be called.
|
||||
</para>
|
||||
|
||||
<note>
|
||||
<para>
|
||||
This struct should only be used, if you know, what you are doing.
|
||||
Do not use this struct unless you know what you are doing.
|
||||
</para>
|
||||
</note>
|
||||
|
||||
@ -155,7 +158,7 @@ will only have to call <literal>g_thread_init (NULL)</literal>.
|
||||
|
||||
<note>
|
||||
<para>
|
||||
You should only call g_thread_init() with a non-%NULL parameter if you
|
||||
Do not call g_thread_init() with a non-%NULL parameter unless you
|
||||
really know what you are doing.
|
||||
</para>
|
||||
</note>
|
||||
@ -163,15 +166,15 @@ really know what you are doing.
|
||||
<note>
|
||||
<para>
|
||||
g_thread_init() must not be called directly or indirectly as a
|
||||
callback from GLib. Also no mutexes may be currently locked, while
|
||||
callback from GLib. Also no mutexes may be currently locked while
|
||||
calling g_thread_init().
|
||||
</para>
|
||||
</note>
|
||||
|
||||
<para>
|
||||
g_thread_init() might only be called once. On the second call
|
||||
it will abort with an error. If you want to make sure, that the thread
|
||||
system is initialized, you can do that too:
|
||||
it will abort with an error. If you want to make sure that the thread
|
||||
system is initialized, you can do this:
|
||||
</para>
|
||||
|
||||
<para>
|
||||
@ -183,9 +186,10 @@ if (!g_thread_supported (<!-- -->)) g_thread_init (NULL);
|
||||
</para>
|
||||
|
||||
<para>
|
||||
After that line either the thread system is initialized or the program
|
||||
will abort, if no thread system is available in GLib, i.e. either
|
||||
#G_THREADS_ENABLED is not defined or #G_THREADS_IMPL_NONE is defined.
|
||||
After that line, either the thread system is initialized or, if no
|
||||
thread system is available in GLib (i.e. either #G_THREADS_ENABLED is
|
||||
not defined or #G_THREADS_IMPL_NONE is defined), the program will
|
||||
abort.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
@ -208,8 +212,8 @@ entry points to the thread system to be used.
|
||||
|
||||
<!-- ##### FUNCTION g_thread_supported ##### -->
|
||||
<para>
|
||||
This function returns, whether the thread system is initialized or
|
||||
not.
|
||||
This function returns %TRUE if the thread system is initialized, and
|
||||
%FALSE if it is not.
|
||||
</para>
|
||||
|
||||
<note>
|
||||
@ -240,7 +244,7 @@ Specifies the priority of a thread.
|
||||
|
||||
<note>
|
||||
<para>
|
||||
It is not guaranteed, that threads with different priorities really
|
||||
It is not guaranteed that threads with different priorities really
|
||||
behave accordingly. On some systems (e.g. Linux) there are no thread
|
||||
priorities. On other systems (e.g. Solaris) there doesn't seem to be
|
||||
different scheduling for different priorities. All in all try to avoid
|
||||
@ -275,8 +279,8 @@ This function creates a new thread with the default priority.
|
||||
|
||||
<para>
|
||||
If @joinable is %TRUE, you can wait for this threads termination
|
||||
calling g_thread_join(). Otherwise the thread will just disappear, when
|
||||
ready.
|
||||
calling g_thread_join(). Otherwise the thread will just disappear when
|
||||
it terminates.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
@ -299,17 +303,19 @@ error is set, if and only if the function returns %NULL.
|
||||
<!-- ##### FUNCTION g_thread_create_full ##### -->
|
||||
<para>
|
||||
This function creates a new thread with the priority @priority. If the
|
||||
underlying thread implementation supports it, the thread gets a stack size
|
||||
of @stack_size or the default value for the current platform, if @stack_size is 0.
|
||||
underlying thread implementation supports it, the thread gets a stack
|
||||
size of @stack_size or the default value for the current platform, if
|
||||
@stack_size is 0.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If @joinable is %TRUE, you can wait for this threads termination
|
||||
calling g_thread_join(). Otherwise the thread will just disappear, when
|
||||
ready. If @bound is %TRUE, this thread will be scheduled in the system
|
||||
scope, otherwise the implementation is free to do scheduling in the
|
||||
process scope. The first variant is more expensive resource-wise, but
|
||||
generally faster. On some systems (e.g. Linux) all threads are bound.
|
||||
calling g_thread_join(). Otherwise the thread will just disappear when
|
||||
it terminates. If @bound is %TRUE, this thread will be scheduled in
|
||||
the system scope, otherwise the implementation is free to do
|
||||
scheduling in the process scope. The first variant is more expensive
|
||||
resource-wise, but generally faster. On some systems (e.g. Linux) all
|
||||
threads are bound.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
@ -324,7 +330,7 @@ error is set, if and only if the function returns %NULL.
|
||||
|
||||
<note>
|
||||
<para>
|
||||
It is not guaranteed, that threads with different priorities really
|
||||
It is not guaranteed that threads with different priorities really
|
||||
behave accordingly. On some systems (e.g. Linux) there are no thread
|
||||
priorities. On other systems (e.g. Solaris) there doesn't seem to be
|
||||
different scheduling for different priorities. All in all try to avoid
|
||||
@ -335,10 +341,10 @@ default.
|
||||
|
||||
<note>
|
||||
<para>
|
||||
Only use g_thread_create_full(), when you really can't use
|
||||
Only use g_thread_create_full() if you really can't use
|
||||
g_thread_create() instead. g_thread_create() does not take
|
||||
@stack_size, @bound and @priority as arguments, as they should only be
|
||||
used for cases, where it is inevitable.
|
||||
@stack_size, @bound, and @priority as arguments, as they should only
|
||||
be used in cases in which it is unavoidable.
|
||||
</para>
|
||||
</note>
|
||||
|
||||
@ -381,7 +387,7 @@ Changes the priority of @thread to @priority.
|
||||
|
||||
<note>
|
||||
<para>
|
||||
It is not guaranteed, that threads with different priorities really
|
||||
It is not guaranteed that threads with different priorities really
|
||||
behave accordingly. On some systems (e.g. Linux) there are no thread
|
||||
priorities. On other systems (e.g. Solaris) there doesn't seem to be
|
||||
different scheduling for different priorities. All in all try to avoid
|
||||
@ -400,8 +406,8 @@ Gives way to other threads waiting to be scheduled.
|
||||
|
||||
<para>
|
||||
This function is often used as a method to make busy wait less
|
||||
evil. But in most cases, you will encounter, there are better methods
|
||||
to do that. So in general you shouldn't use that function.
|
||||
evil. But in most cases you will encounter, there are better methods
|
||||
to do that. So in general you shouldn't use this function.
|
||||
</para>
|
||||
|
||||
|
||||
@ -410,7 +416,7 @@ to do that. So in general you shouldn't use that function.
|
||||
<para>
|
||||
Exits the current thread. If another thread is waiting for that thread
|
||||
using g_thread_join() and the current thread is joinable, the waiting
|
||||
thread will be woken up and getting @retval as the return value of
|
||||
thread will be woken up and get @retval as the return value of
|
||||
g_thread_join(). If the current thread is not joinable, @retval is
|
||||
ignored. Calling
|
||||
</para>
|
||||
@ -482,7 +488,7 @@ access. Take for example the following function:
|
||||
</para>
|
||||
|
||||
<para>
|
||||
It is easy to see, that this won't work in a multi-threaded
|
||||
It is easy to see that this won't work in a multi-threaded
|
||||
application. There current_number must be protected against shared
|
||||
access. A first naive implementation would be:
|
||||
</para>
|
||||
@ -510,8 +516,8 @@ access. A first naive implementation would be:
|
||||
|
||||
<para>
|
||||
This looks like it would work, but there is a race condition while
|
||||
constructing the mutex and this code cannot work reliable. So please do
|
||||
not use such constructs in your own programs. One working solution is:
|
||||
constructing the mutex and this code cannot work reliable. Please do
|
||||
not use such constructs in your own programs! One working solution is:
|
||||
</para>
|
||||
|
||||
<para>
|
||||
@ -547,9 +553,10 @@ not use such constructs in your own programs. One working solution is:
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If you want to use a mutex, but your code should also work without
|
||||
calling g_thread_init() first, you can not use a #GMutex, as
|
||||
g_mutex_new() requires that. Use a #GStaticMutex instead.
|
||||
If you want to use a mutex, and your code should also work without
|
||||
calling g_thread_init() first, then you can not use a #GMutex, as
|
||||
g_mutex_new() requires that the thread system be initialized. Use a
|
||||
#GStaticMutex instead.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
@ -573,7 +580,7 @@ Creates a new #GMutex.
|
||||
|
||||
<note>
|
||||
<para>
|
||||
This function will abort, if g_thread_init() has not been called yet.
|
||||
This function will abort if g_thread_init() has not been called yet.
|
||||
</para>
|
||||
</note>
|
||||
|
||||
@ -589,8 +596,8 @@ thread.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
This function can also be used, if g_thread_init() has not yet been
|
||||
called and will do nothing then.
|
||||
This function can be used even if g_thread_init() has not yet been
|
||||
called, and, in that case, will do nothing.
|
||||
</para>
|
||||
|
||||
<note>
|
||||
@ -614,8 +621,8 @@ and returns %TRUE.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
This function can also be used, if g_thread_init() has not yet been
|
||||
called and will immediately return %TRUE then.
|
||||
This function can be used even if g_thread_init() has not yet been
|
||||
called, and, in that case, will immediately return %TRUE.
|
||||
</para>
|
||||
|
||||
<note>
|
||||
@ -639,8 +646,8 @@ for @mutex, it will be woken and can lock @mutex itself.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
This function can also be used, if g_thread_init() has not yet been
|
||||
called and will do nothing then.
|
||||
This function can be used even if g_thread_init() has not yet been
|
||||
called, and, in that case, will do nothing.
|
||||
</para>
|
||||
|
||||
@mutex: a #GMutex.
|
||||
@ -702,7 +709,7 @@ platforms.
|
||||
|
||||
<para>
|
||||
All of the <function>g_static_mutex_*</function> functions can also be
|
||||
used, if g_thread_init() has not yet been called.
|
||||
used even if g_thread_init() has not yet been called.
|
||||
</para>
|
||||
|
||||
<note>
|
||||
@ -802,11 +809,11 @@ you should also free the #GStaticMutex.
|
||||
The %G_LOCK_* macros provide a convenient interface to #GStaticMutex
|
||||
with the advantage that they will expand to nothing in programs
|
||||
compiled against a thread-disabled GLib, saving code and memory
|
||||
there. #G_LOCK_DEFINE defines a lock. It can appear, where variable
|
||||
there. #G_LOCK_DEFINE defines a lock. It can appear anywhere variable
|
||||
definitions may appear in programs, i.e. in the first block of a
|
||||
function or outside of functions. The @name parameter will be mangled
|
||||
to get the name of the #GStaticMutex. This means, that you can use
|
||||
names of existing variables as the parameter, e.g. the name of the
|
||||
to get the name of the #GStaticMutex. This means that you can use
|
||||
names of existing variables as the parameter - e.g. the name of the
|
||||
variable you intent to protect with the lock. Look at our
|
||||
<function>give_me_next_number()</function> example using the %G_LOCK_* macros:
|
||||
</para>
|
||||
@ -883,12 +890,13 @@ Works like g_mutex_unlock(), but for a lock defined with #G_LOCK_DEFINE.
|
||||
<!-- ##### STRUCT GStaticRecMutex ##### -->
|
||||
<para>
|
||||
A #GStaticRecMutex works like a #GStaticMutex, but it can be locked
|
||||
multiple times by one thread. If you enter it n times, however, you
|
||||
have to unlock it n times again to let other threads lock it. An
|
||||
exception is the function g_static_rec_mutex_unlock_full(), that
|
||||
allows you to unlock a #GStaticRecMutex completely returning the depth,
|
||||
i.e. the number of times this mutex was locked. The depth can later be
|
||||
used to restore the state by calling g_static_rec_mutex_lock_full().
|
||||
multiple times by one thread. If you enter it n times, you have to
|
||||
unlock it n times again to let other threads lock it. An exception is
|
||||
the function g_static_rec_mutex_unlock_full(): that allows you to
|
||||
unlock a #GStaticRecMutex completely returning the depth, (i.e. the
|
||||
number of times this mutex was locked). The depth can later be used to
|
||||
restore the state of the #GStaticRecMutex by calling
|
||||
g_static_rec_mutex_lock_full().
|
||||
</para>
|
||||
|
||||
<para>
|
||||
@ -897,14 +905,14 @@ the following functions.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
All of the <function>g_static_rec_mutex_*</function> functions can also
|
||||
be used, if g_thread_init() has not been called.
|
||||
All of the <function>g_static_rec_mutex_*</function> functions can
|
||||
be used even if g_thread_init() has not been called.
|
||||
</para>
|
||||
|
||||
|
||||
<!-- ##### MACRO G_STATIC_REC_MUTEX_INIT ##### -->
|
||||
<para>
|
||||
A #GStaticRecMutex must be initialized with this macro, before it can
|
||||
A #GStaticRecMutex must be initialized with this macro before it can
|
||||
be used. This macro can used be to initialize a variable, but it
|
||||
cannot be assigned to a variable. In that case you have to use
|
||||
g_static_rec_mutex_init().
|
||||
@ -922,7 +930,7 @@ GStaticRecMutex my_mutex = G_STATIC_REC_MUTEX_INIT;
|
||||
|
||||
<!-- ##### FUNCTION g_static_rec_mutex_init ##### -->
|
||||
<para>
|
||||
A #GStaticRecMutex must be initialized with this function, before it
|
||||
A #GStaticRecMutex must be initialized with this function before it
|
||||
can be used. Alternatively you can initialize it with
|
||||
#G_STATIC_REC_MUTEX_INIT.
|
||||
</para>
|
||||
@ -955,11 +963,11 @@ functions increases the depth of @mutex and immediately returns %TRUE.
|
||||
|
||||
<!-- ##### FUNCTION g_static_rec_mutex_unlock ##### -->
|
||||
<para>
|
||||
Unlocks @mutex. Another threads can, however, only lock @mutex when it
|
||||
has been unlocked as many times, as it had been locked before. If
|
||||
@mutex is completely unlocked and another thread is blocked in a
|
||||
g_static_rec_mutex_lock() call for @mutex, it will be woken and can
|
||||
lock @mutex itself.
|
||||
Unlocks @mutex. Another thread can will be allowed to lock @mutex only
|
||||
when it has been unlocked as many times as it had been locked
|
||||
before. If @mutex is completely unlocked and another thread is blocked
|
||||
in a g_static_rec_mutex_lock() call for @mutex, it will be woken and
|
||||
can lock @mutex itself.
|
||||
</para>
|
||||
|
||||
@mutex: a #GStaticRecMutex to unlock.
|
||||
@ -978,7 +986,7 @@ Works like calling g_static_rec_mutex_lock() for @mutex @depth times.
|
||||
<para>
|
||||
Completely unlocks @mutex. If another thread is blocked in a
|
||||
g_static_rec_mutex_lock() call for @mutex, it will be woken and can
|
||||
lock @mutex itself. This function returns the number of times, that
|
||||
lock @mutex itself. This function returns the number of times that
|
||||
@mutex has been locked by the current thread. To restore the state
|
||||
before the call to g_static_rec_mutex_unlock_full() you can call
|
||||
g_static_rec_mutex_lock_full() with the depth returned by this
|
||||
@ -1007,9 +1015,9 @@ freed, you should also free the #GStaticRecMutex.
|
||||
<!-- ##### STRUCT GStaticRWLock ##### -->
|
||||
<para>
|
||||
The #GStaticRWLock struct represents a read-write lock. A read-write
|
||||
lock can be used for protecting data, that some portions of code only
|
||||
lock can be used for protecting data that some portions of code only
|
||||
read from, while others also write. In such situations it is
|
||||
desirable, that several readers can read at once, whereas of course
|
||||
desirable that several readers can read at once, whereas of course
|
||||
only one writer may write at a time. Take a look at the following
|
||||
example:
|
||||
|
||||
@ -1056,19 +1064,19 @@ example:
|
||||
</para>
|
||||
|
||||
<para>
|
||||
This example shows an array, which can be accessed by many readers
|
||||
This example shows an array which can be accessed by many readers
|
||||
(the <function>my_array_get()</function> function) simultaneously,
|
||||
whereas the writers (the <function>my_array_set()</function> function)
|
||||
will only be allowed once a time and only if no readers currently access
|
||||
will only be allowed once at a time and only if no readers currently access
|
||||
the array. This is because of the potentially dangerous resizing of the
|
||||
array. Using these functions is fully multi-thread safe now.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Most of the time the writers should have precedence of readers. That
|
||||
means for this implementation, that as soon as a writer wants to lock
|
||||
the data, no other reader is allowed to lock the data, whereas of
|
||||
course the readers, that already have locked the data are allowed to
|
||||
Most of the time, writers should have precedence over readers. That
|
||||
means, for this implementation, that as soon as a writer wants to lock
|
||||
the data, no other reader is allowed to lock the data, whereas, of
|
||||
course, the readers that already have locked the data are allowed to
|
||||
finish their operation. As soon as the last reader unlocks the data,
|
||||
the writer will lock it.
|
||||
</para>
|
||||
@ -1079,18 +1087,18 @@ the following functions.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
All of the <function>g_static_rw_lock_*</function> functions can also be
|
||||
used, if g_thread_init() has not been called.
|
||||
All of the <function>g_static_rw_lock_*</function> functions can be
|
||||
used even if g_thread_init() has not been called.
|
||||
</para>
|
||||
|
||||
<note>
|
||||
<para>
|
||||
A read-write lock has a higher overhead as a mutex. For example both
|
||||
A read-write lock has a higher overhead than a mutex. For example, both
|
||||
g_static_rw_lock_reader_lock() and g_static_rw_lock_reader_unlock()
|
||||
have to lock and unlock a #GStaticMutex, so it takes at least twice the
|
||||
time to lock and unlock a #GStaticRWLock than to lock and unlock a
|
||||
#GStaticMutex. So only data structures, that are accessed by multiple
|
||||
readers, which keep the lock for a considerable time justify a
|
||||
time to lock and unlock a #GStaticRWLock that it does to lock and unlock a
|
||||
#GStaticMutex. So only data structures that are accessed by multiple
|
||||
readers, and which keep the lock for a considerable time justify a
|
||||
#GStaticRWLock. The above example most probably would fare better with
|
||||
a #GStaticMutex.
|
||||
</para>
|
||||
@ -1099,7 +1107,7 @@ a #GStaticMutex.
|
||||
|
||||
<!-- ##### MACRO G_STATIC_RW_LOCK_INIT ##### -->
|
||||
<para>
|
||||
A #GStaticRWLock must be initialized with this macro, before it can
|
||||
A #GStaticRWLock must be initialized with this macro before it can
|
||||
be used. This macro can used be to initialize a variable, but it
|
||||
cannot be assigned to a variable. In that case you have to use
|
||||
g_static_rw_lock_init().
|
||||
@ -1117,7 +1125,7 @@ GStaticRWLock my_lock = G_STATIC_RW_LOCK_INIT;
|
||||
|
||||
<!-- ##### FUNCTION g_static_rw_lock_init ##### -->
|
||||
<para>
|
||||
A #GStaticRWLock must be initialized with this function, before it can
|
||||
A #GStaticRWLock must be initialized with this function before it can
|
||||
be used. Alternatively you can initialize it with
|
||||
#G_STATIC_RW_LOCK_INIT.
|
||||
</para>
|
||||
@ -1138,8 +1146,8 @@ g_static_rw_lock_reader_unlock().
|
||||
|
||||
<para>
|
||||
#GStaticRWLock is not recursive. It might seem to be possible to
|
||||
recursively lock for reading, but that can result in a deadlock as
|
||||
well, due to writer preference.
|
||||
recursively lock for reading, but that can result in a deadlock, due
|
||||
to writer preference.
|
||||
</para>
|
||||
|
||||
@lock: a #GStaticRWLock to lock for reading.
|
||||
@ -1149,9 +1157,9 @@ well, due to writer preference.
|
||||
<para>
|
||||
Tries to lock @lock for reading. If @lock is already locked for
|
||||
writing by another thread or if another thread is already waiting to
|
||||
lock @lock for writing, it immediately returns %FALSE. Otherwise it
|
||||
locks @lock for reading and returns %TRUE. This lock has to be unlocked
|
||||
by g_static_rw_lock_reader_unlock().
|
||||
lock @lock for writing, immediately returns %FALSE. Otherwise locks
|
||||
@lock for reading and returns %TRUE. This lock has to be unlocked by
|
||||
g_static_rw_lock_reader_unlock().
|
||||
</para>
|
||||
|
||||
@lock: a #GStaticRWLock to lock for reading.
|
||||
@ -1196,11 +1204,12 @@ lock has to be unlocked by g_static_rw_lock_writer_unlock().
|
||||
|
||||
<!-- ##### FUNCTION g_static_rw_lock_writer_unlock ##### -->
|
||||
<para>
|
||||
Unlocks @lock. If a thread waits to lock @lock for writing and all
|
||||
locks for reading have been unlocked, the waiting thread is woken up
|
||||
and can lock @lock for writing. If no thread waits to lock @lock for
|
||||
writing and threads wait to lock @lock for reading, the waiting
|
||||
threads are woken up and can lock @lock for reading.
|
||||
Unlocks @lock. If a thread is waiting to lock @lock for writing and
|
||||
all locks for reading have been unlocked, the waiting thread is woken
|
||||
up and can lock @lock for writing. If no thread is waiting to lock
|
||||
@lock for writing, and some thread or threads are waiting to lock @lock
|
||||
for reading, the waiting threads are woken up and can lock @lock for
|
||||
reading.
|
||||
</para>
|
||||
|
||||
@lock: a #GStaticRWLock to unlock after writing.
|
||||
@ -1214,7 +1223,7 @@ Releases all resources allocated to @lock.
|
||||
<para>
|
||||
You don't have to call this functions for a #GStaticRWLock with an
|
||||
unbounded lifetime, i.e. objects declared 'static', but if you have a
|
||||
#GStaticRWLock as a member of a structure and the structure is freed,
|
||||
#GStaticRWLock as a member of a structure, and the structure is freed,
|
||||
you should also free the #GStaticRWLock.
|
||||
</para>
|
||||
|
||||
@ -1224,11 +1233,11 @@ you should also free the #GStaticRWLock.
|
||||
<!-- ##### STRUCT GCond ##### -->
|
||||
|
||||
<para>
|
||||
The #GCond struct is an opaque data structure to represent a
|
||||
condition. A #GCond is an object, that threads can block on, if they
|
||||
find a certain condition to be false. If other threads change the
|
||||
state of this condition they can signal the #GCond, such that the
|
||||
waiting thread is woken up.
|
||||
The #GCond struct is an opaque data structure that represents a
|
||||
condition. Threads can block on a #GCond if they find a certain
|
||||
condition to be false. If other threads change the state of this
|
||||
condition they signal the #GCond, and that causes the waiting threads
|
||||
to be woken up.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
@ -1272,11 +1281,11 @@ has called <function>push_data()</function>.
|
||||
<note>
|
||||
<para>
|
||||
It is important to use the g_cond_wait() and g_cond_timed_wait()
|
||||
functions only inside a loop, which checks for the condition to be
|
||||
true as it is not guaranteed that the waiting thread will find it
|
||||
fulfilled, even if the signaling thread left the condition
|
||||
in that state. This is because another thread can have altered the
|
||||
condition, before the waiting thread got the chance to be woken up,
|
||||
functions only inside a loop which checks for the condition to be
|
||||
true. It is not guaranteed that the waiting thread will find the
|
||||
condition fulfilled after it wakes up, even if the signaling thread
|
||||
left the condition in that state: another thread may have altered the
|
||||
condition before the waiting thread got the chance to be woken up,
|
||||
even if the condition itself is protected by a #GMutex, like above.
|
||||
</para>
|
||||
</note>
|
||||
@ -1307,13 +1316,13 @@ has not been called yet.
|
||||
<!-- ##### FUNCTION g_cond_signal ##### -->
|
||||
<para>
|
||||
If threads are waiting for @cond, exactly one of them is woken up. It
|
||||
is good practice to hold the same lock as the waiting thread, while
|
||||
is good practice to hold the same lock as the waiting thread while
|
||||
calling this function, though not required.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
This function can also be used, if g_thread_init() has
|
||||
not yet been called and will do nothing then.
|
||||
This function can be used even if g_thread_init() has not yet been called,
|
||||
and, in that case, will do nothing.
|
||||
</para>
|
||||
|
||||
@cond: a #GCond.
|
||||
@ -1328,8 +1337,8 @@ this function, though not required.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
This function can also be used, if g_thread_init() has
|
||||
not yet been called and will do nothing then.
|
||||
This function can be used even if g_thread_init() has not yet been called,
|
||||
and, in that case, will do nothing.
|
||||
</para>
|
||||
|
||||
@cond: a #GCond.
|
||||
@ -1343,8 +1352,8 @@ before falling asleep and locked again before resuming.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
This function can also be used, if g_thread_init() has not yet been
|
||||
called and will immediately return then.
|
||||
This function can be used even if g_thread_init() has not yet been
|
||||
called, and, in that case, will immediately return.
|
||||
</para>
|
||||
|
||||
@cond: a #GCond.
|
||||
@ -1355,7 +1364,7 @@ called and will immediately return then.
|
||||
|
||||
<para>
|
||||
Waits until this thread is woken up on @cond, but not longer than
|
||||
until the time, that is specified by @abs_time. The @mutex is
|
||||
until the time specified by @abs_time. The @mutex is
|
||||
unlocked before falling asleep and locked again before resuming.
|
||||
</para>
|
||||
|
||||
@ -1364,8 +1373,8 @@ If @abs_time is %NULL, g_cond_timed_wait() acts like g_cond_wait().
|
||||
</para>
|
||||
|
||||
<para>
|
||||
This function can also be used, if g_thread_init() has not yet been
|
||||
called and will immediately return %TRUE then.
|
||||
This function can be used even if g_thread_init() has not yet been
|
||||
called, and, in that case, will immediately return %TRUE.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
@ -1374,9 +1383,9 @@ and g_time_val_add() can be used.
|
||||
</para>
|
||||
|
||||
@cond: a #GCond.
|
||||
@mutex: a #GMutex, that is currently locked.
|
||||
@mutex: a #GMutex that is currently locked.
|
||||
@abs_time: a #GTimeVal, determining the final time.
|
||||
@Returns: %TRUE, if the thread is woken up in time.
|
||||
@Returns: %TRUE if @cond was signalled, or %FALSE on timeout.
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_cond_free ##### -->
|
||||
@ -1391,11 +1400,11 @@ Destroys the #GCond.
|
||||
<!-- ##### STRUCT GPrivate ##### -->
|
||||
<para>
|
||||
The #GPrivate struct is an opaque data structure to represent a thread
|
||||
private data key. Threads can thereby obtain and set a pointer, which
|
||||
private data key. Threads can thereby obtain and set a pointer which
|
||||
is private to the current thread.
|
||||
Take our <function>give_me_next_number()</function> example from above.
|
||||
Now we don't want <literal>current_number</literal> to be shared
|
||||
between the threads, but to be private to each thread. This can be
|
||||
Suppose we don't want <literal>current_number</literal> to be shared
|
||||
between the threads, but instead to be private to each thread. This can be
|
||||
done as follows:
|
||||
|
||||
<example>
|
||||
@ -1425,7 +1434,7 @@ done as follows:
|
||||
Here the pointer belonging to the key <literal>current_number_key</literal>
|
||||
is read. If it is %NULL, it has not been set yet. Then get memory for an
|
||||
integer value, assign this memory to the pointer and write the pointer
|
||||
back. Now we have an integer value, that is private to the current thread.
|
||||
back. Now we have an integer value that is private to the current thread.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
@ -1452,25 +1461,25 @@ destructor is called with this pointer as the argument.
|
||||
|
||||
<note>
|
||||
<para>
|
||||
@destructor is working quite differently from @notify in
|
||||
@destructor is used quite differently from @notify in
|
||||
g_static_private_set().
|
||||
</para>
|
||||
</note>
|
||||
|
||||
<note>
|
||||
<para>
|
||||
A #GPrivate can not be freed. Reuse it instead, if you can to avoid
|
||||
shortage or use #GStaticPrivate.
|
||||
A #GPrivate can not be freed. Reuse it instead, if you can, to avoid
|
||||
shortage, or use #GStaticPrivate.
|
||||
</para>
|
||||
</note>
|
||||
|
||||
<note>
|
||||
<para>
|
||||
This function will abort, if g_thread_init() has not been called yet.
|
||||
This function will abort if g_thread_init() has not been called yet.
|
||||
</para>
|
||||
</note>
|
||||
|
||||
@destructor: a function to handle the data keyed to #GPrivate, when a
|
||||
@destructor: a function to destroy the data keyed to #GPrivate when a
|
||||
thread ends.
|
||||
@Returns: a new #GPrivate.
|
||||
|
||||
@ -1478,14 +1487,14 @@ thread ends.
|
||||
<!-- ##### FUNCTION g_private_get ##### -->
|
||||
|
||||
<para>
|
||||
Returns the pointer keyed to @private_key for the current thread. This
|
||||
pointer is %NULL, when g_private_set() hasn't been called for the
|
||||
current @private_key and thread yet.
|
||||
Returns the pointer keyed to @private_key for the current thread.
|
||||
If g_private_set() hasn't been called for the
|
||||
current @private_key and thread yet, this pointer will be %NULL.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
This function can also be used, if g_thread_init() has not yet been
|
||||
called and will return the value of @private_key casted to #gpointer then.
|
||||
This function can be used even if g_thread_init() has not yet been
|
||||
called, and, in that case, will return the value of @private_key casted to #gpointer.
|
||||
</para>
|
||||
|
||||
@private_key: a #GPrivate.
|
||||
@ -1499,8 +1508,8 @@ Sets the pointer keyed to @private_key for the current thread.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
This function can also be used, if g_thread_init() has not yet been
|
||||
called and will set @private_key to @data casted to #GPrivate* then.
|
||||
This function can be used even if g_thread_init() has not yet been
|
||||
called, and, in that case, will set @private_key to @data casted to #GPrivate*.
|
||||
</para>
|
||||
|
||||
@private_key: a #GPrivate.
|
||||
@ -1571,7 +1580,7 @@ Works like g_private_get() only for a #GStaticPrivate.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
This function also works, if g_thread_init() has not yet been called.
|
||||
This function works even if g_thread_init() has not yet been called.
|
||||
</para>
|
||||
|
||||
@private_key: a #GStaticPrivate.
|
||||
@ -1586,7 +1595,7 @@ whenever the pointer is set again or whenever the current thread ends.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
This function also works, if g_thread_init() has not yet been
|
||||
This function works even if g_thread_init() has not yet been
|
||||
called. If g_thread_init() is called later, the @data keyed to
|
||||
@private_key will be inherited only by the main thread, i.e. the one that
|
||||
called g_thread_init().
|
||||
@ -1594,14 +1603,14 @@ called g_thread_init().
|
||||
|
||||
<note>
|
||||
<para>
|
||||
@notify is working quite differently from @destructor in
|
||||
@notify is used quite differently from @destructor in
|
||||
g_private_new().
|
||||
</para>
|
||||
</note>
|
||||
|
||||
@private_key: a #GStaticPrivate.
|
||||
@data: the new pointer.
|
||||
@notify: a function to be called with the pointer, whenever the
|
||||
@notify: a function to be called with the pointer whenever the
|
||||
current thread ends or sets this pointer again.
|
||||
|
||||
|
||||
@ -1634,7 +1643,7 @@ function. Any one-time initialization function must have its own unique
|
||||
|
||||
<!-- ##### ENUM GOnceStatus ##### -->
|
||||
<para>
|
||||
The possible stati of a one-time initialization function controlled by a #GOnce struct.
|
||||
The possible statuses of a one-time initialization function controlled by a #GOnce struct.
|
||||
</para>
|
||||
|
||||
@G_ONCE_STATUS_NOTCALLED: the function has not been called yet.
|
||||
@ -1644,7 +1653,7 @@ The possible stati of a one-time initialization function controlled by a #GOnce
|
||||
|
||||
<!-- ##### MACRO G_ONCE_INIT ##### -->
|
||||
<para>
|
||||
A #GOnce must be initialized with this macro, before it can be used.
|
||||
A #GOnce must be initialized with this macro before it can be used.
|
||||
</para>
|
||||
<para>
|
||||
<informalexample>
|
||||
|
||||
@ -58,7 +58,7 @@ type.
|
||||
<!-- ##### MACRO G_TYPE_FUNDAMENTAL ##### -->
|
||||
<para>
|
||||
Returns the fundamental type which is the ancestor of @type.
|
||||
Fundamental types are types that serve as fundaments for the derived types,
|
||||
Fundamental types are types that serve as ultimate bases for the derived types,
|
||||
thus they are the roots of distinct inheritance hierarchies.
|
||||
</para>
|
||||
|
||||
@ -113,7 +113,7 @@ Returns %TRUE if @type is a fundamental type.
|
||||
|
||||
<!-- ##### MACRO G_TYPE_IS_VALUE_TYPE ##### -->
|
||||
<para>
|
||||
Returns %TRUE if @type is a value type which can be used for
|
||||
Returns %TRUE if @type is a value type and can be used with
|
||||
g_value_init().
|
||||
</para>
|
||||
|
||||
@ -166,7 +166,7 @@ can be used as the base class of a deep (multi-level) class hierarchy.
|
||||
<!-- ##### MACRO G_TYPE_IS_INTERFACE ##### -->
|
||||
<para>
|
||||
Returns %TRUE if @type is an interface type.
|
||||
Interface types are types that provide pure APIs, the implementation
|
||||
An interface type provides a pure API, the implementation
|
||||
of which is provided by another type (which is then said to conform
|
||||
to the interface). GLib interfaces are somewhat analogous to Java
|
||||
interfaces and C++ classes containing only pure virtual functions,
|
||||
@ -199,11 +199,11 @@ An opaque structure used as the base of all classes.
|
||||
<para>
|
||||
This structure is used to provide the type system with the information
|
||||
required to initialize and destruct (finalize) a type's class and
|
||||
instances thereof.
|
||||
its instances.
|
||||
The initialized structure is passed to the g_type_register_static() function
|
||||
(or is copied into the provided #GTypeInfo structure in the
|
||||
g_type_plugin_complete_type_info()). The type system will perform a deep
|
||||
copy of this structure, so it's memory does not need to be persistent
|
||||
copy of this structure, so its memory does not need to be persistent
|
||||
across invocation of g_type_register_static().
|
||||
</para>
|
||||
|
||||
@ -295,8 +295,8 @@ to serve as a container for values of a type.
|
||||
}
|
||||
</programlisting>
|
||||
@collect_format: A string format describing how to collect the contents of
|
||||
this value, bit-by-bit. Each character in the format represents
|
||||
an argument to be collected, the characters themselves indicate
|
||||
this value bit-by-bit. Each character in the format represents
|
||||
an argument to be collected, and the characters themselves indicate
|
||||
the type of the argument. Currently supported arguments are:
|
||||
<variablelist>
|
||||
<varlistentry><term></term><listitem><para>
|
||||
@ -312,14 +312,14 @@ to serve as a container for values of a type.
|
||||
'p' - Pointers. passed as collect_values[].v_pointer.
|
||||
</para></listitem></varlistentry>
|
||||
</variablelist>
|
||||
It should be noted, that for variable argument list construction,
|
||||
It should be noted that for variable argument list construction,
|
||||
ANSI C promotes every type smaller than an integer to an int, and
|
||||
floats to doubles. So for collection of short int or char, 'i'
|
||||
needs to be used, and for collection of floats 'd'.
|
||||
@collect_value: The collect_value() function is responsible for converting the
|
||||
values collected from a variable argument list into contents
|
||||
suitable for storage in a GValue. This function should setup
|
||||
@value similar to value_init(), e.g. for a string value that
|
||||
@value similar to value_init(); e.g. for a string value that
|
||||
does not allow %NULL pointers, it needs to either spew an error,
|
||||
or do an implicit conversion by storing an empty string.
|
||||
The @value passed in to this function has a zero-filled data
|
||||
@ -329,8 +329,8 @@ to serve as a container for values of a type.
|
||||
and @collect_values is an array of unions #GTypeCValue with
|
||||
length @n_collect_values, containing the collected values
|
||||
according to @collect_format.
|
||||
@collect_flags is an argument provided as a hint by the caller,
|
||||
which may contain the flag #G_VALUE_NOCOPY_CONTENTS indicating,
|
||||
@collect_flags is an argument provided as a hint by the caller.
|
||||
It may contain the flag #G_VALUE_NOCOPY_CONTENTS indicating,
|
||||
that the collected value contents may be considered "static"
|
||||
for the duration of the @value lifetime.
|
||||
Thus an extra copy of the contents stored in @collect_values is
|
||||
@ -376,8 +376,8 @@ to serve as a container for values of a type.
|
||||
The reference count for valid objects is always incremented,
|
||||
regardless of @collect_flags. For invalid objects, the example
|
||||
returns a newly allocated string without altering @value.
|
||||
Upon success, collect_value() needs to return %NULL, if however
|
||||
a malicious condition occurred, collect_value() may spew an
|
||||
Upon success, collect_value() needs to return %NULL. If, however,
|
||||
an error condition occurred, collect_value() may spew an
|
||||
error by returning a newly allocated non-%NULL string, giving
|
||||
a suitable description of the error condition.
|
||||
The calling code makes no assumptions about the @value
|
||||
@ -415,7 +415,7 @@ to serve as a container for values of a type.
|
||||
|
||||
}
|
||||
</programlisting>
|
||||
And an exemplary version of lcopy_value() for
|
||||
And an illustrative version of lcopy_value() for
|
||||
reference-counted types:
|
||||
<programlisting>
|
||||
{
|
||||
@ -666,7 +666,7 @@ Return the corresponding quark of the type IDs name.
|
||||
|
||||
<!-- ##### FUNCTION g_type_from_name ##### -->
|
||||
<para>
|
||||
Lookup the type ID from a given type name, returns 0 if no type has been registered under this name
|
||||
Lookup the type ID from a given type name, returning 0 if no type has been registered under this name
|
||||
(this is the preferred method to find out by name whether a specific type has been registered yet).
|
||||
</para>
|
||||
|
||||
@ -734,7 +734,7 @@ exist already.
|
||||
<!-- ##### FUNCTION g_type_class_peek ##### -->
|
||||
<para>
|
||||
This function is essentially the same as g_type_class_ref(), except that
|
||||
the classes reference count isn't incremented. Therefore, this function
|
||||
the classes reference count isn't incremented. As a consequence, this function
|
||||
may return %NULL if the class of the type passed in does not currently
|
||||
exist (hasn't been referenced before).
|
||||
</para>
|
||||
@ -769,9 +769,9 @@ class pointer after g_type_class_unref() are invalid.
|
||||
|
||||
<!-- ##### FUNCTION g_type_class_peek_parent ##### -->
|
||||
<para>
|
||||
This is a convenience function, often needed in class initializers.
|
||||
It essentially takes the immediate parent type of the class passed in,
|
||||
and returns the class structure thereof. Since derived classes hold
|
||||
This is a convenience function often needed in class initializers.
|
||||
It returns the class structure of the immediate parent type of the class passed in.
|
||||
Since derived classes hold
|
||||
a reference count on their parent classes as long as they are instantiated,
|
||||
the returned class will always exist. This function is essentially
|
||||
equivalent to:
|
||||
@ -886,7 +886,7 @@ its default interface vtable.
|
||||
</para>
|
||||
|
||||
@g_type: an interface type
|
||||
@Returns: the default vtable for the interface; or %NULL
|
||||
@Returns: the default vtable for the interface, or %NULL
|
||||
if the type is not currently in use.
|
||||
@Since: 2.4
|
||||
|
||||
@ -993,7 +993,7 @@ A callback function used by the type system to do base initialization
|
||||
of the class structures of derived types. It is called as part of the
|
||||
initialization process of all derived classes and should reallocate
|
||||
or reset all dynamic class members copied over from the parent class.
|
||||
Therefore class members, e.g. strings, that are not sufficiently
|
||||
For example, class members (such as strings) that are not sufficiently
|
||||
handled by a plain memory copy of the parent class into the derived class
|
||||
have to be altered. See GClassInitFunc() for a discussion of the class
|
||||
intialization process.
|
||||
@ -1097,8 +1097,8 @@ Initialization of TypeBClass will first cause initialization of
|
||||
TypeAClass (derived classes reference their parent classes, see
|
||||
g_type_class_ref() on this).
|
||||
Initialization of TypeAClass roughly involves zero-initializing its fields,
|
||||
then calling its GBaseInitFunc() type_a_base_class_init() that allocates
|
||||
its dynamic members (dynamic_string) and finally calling its GClassInitFunc()
|
||||
then calling its GBaseInitFunc() type_a_base_class_init() to allocate
|
||||
its dynamic members (dynamic_string), and finally calling its GClassInitFunc()
|
||||
type_a_class_init() to initialize its static members (static_integer).
|
||||
The first step in the initialization process of TypeBClass is then
|
||||
a plain memory copy of the contents of TypeAClass into TypeBClass and
|
||||
@ -1141,7 +1141,7 @@ A callback function used by the type system to initialize a new
|
||||
instance of a type. This function initializes all instance members and
|
||||
allocates any resources required by it.
|
||||
Initialization of a derived instance involves calling all its parent
|
||||
types instance initializers, therefore the class member of the instance
|
||||
types instance initializers, so the class member of the instance
|
||||
is altered during its initialization to always point to the class that
|
||||
belongs to the type the current initializer was introduced for.
|
||||
</para>
|
||||
@ -1223,7 +1223,7 @@ instances (if not abstract). The value of @flags determines the nature
|
||||
(e.g. abstract or not) of the type.
|
||||
</para>
|
||||
|
||||
@parent_type: Type which this type will be derived from.
|
||||
@parent_type: Type from which this type will be derived.
|
||||
@type_name: 0-terminated string used as the name of the new type.
|
||||
@info: The #GTypeInfo structure for this type.
|
||||
@flags: Bitwise combination of #GTypeFlags values.
|
||||
@ -1238,7 +1238,7 @@ abstract or not) of the type. It works by filling a #GTypeInfo
|
||||
struct and calling g_type_info_register_static().
|
||||
</para>
|
||||
|
||||
@parent_type: Type which this type will be derived from.
|
||||
@parent_type: Type from which this type will be derived.
|
||||
@type_name: 0-terminated string used as the name of the new type.
|
||||
@class_size: Size of the class structure (see #GTypeInfo)
|
||||
@class_init: Location of the class initialization function (see #GTypeInfo)
|
||||
@ -1258,7 +1258,7 @@ instances (if not abstract). The value of @flags determines the nature
|
||||
(e.g. abstract or not) of the type.
|
||||
</para>
|
||||
|
||||
@parent_type: Type which this type will be derived from.
|
||||
@parent_type: Type from which this type will be derived.
|
||||
@type_name: 0-terminated string used as the name of the new type.
|
||||
@plugin: The #GTypePlugin structure to retrieve the #GTypeInfo from.
|
||||
@flags: Bitwise combination of #GTypeFlags values.
|
||||
@ -1373,7 +1373,7 @@ use G_TYPE_FUNDAMENTAL() instead.
|
||||
<para>
|
||||
Creates and initializes an instance of @type if @type is valid and can
|
||||
be instantiated. The type system only performs basic allocation and
|
||||
structure setups for instances, actual instance creation should happen
|
||||
structure setups for instances: actual instance creation should happen
|
||||
through functions supplied by the type's fundamental type implementation.
|
||||
So use of g_type_create_instance() is reserved for implementators of
|
||||
fundamental types only. E.g. instances of the #GObject hierarchy
|
||||
@ -1442,8 +1442,8 @@ otherwise.
|
||||
<!-- ##### FUNCTION g_type_add_interface_check ##### -->
|
||||
<para>
|
||||
Adds a function to be called after an interface vtable is
|
||||
initialized for any class. That is, after the @interface_init
|
||||
member of #GInterfaceInfo has been called.
|
||||
initialized for any class (i.e. after the @interface_init
|
||||
member of #GInterfaceInfo has been called).
|
||||
</para>
|
||||
<para>
|
||||
This function is useful when you want to check an invariant
|
||||
@ -1484,7 +1484,7 @@ See g_type_add_interface_check().
|
||||
<!-- ##### FUNCTION g_type_value_table_peek ##### -->
|
||||
<para>
|
||||
Returns the location of the #GTypeValueTable associated with @type.
|
||||
<emphasis>Note, this function should only be used from source code
|
||||
<emphasis>Note that this function should only be used from source code
|
||||
that implements or has internal knowledge of the implementation of
|
||||
@type.</emphasis>
|
||||
</para>
|
||||
@ -1644,7 +1644,7 @@ init functions.
|
||||
|
||||
<!-- ##### MACRO G_TYPE_INVALID ##### -->
|
||||
<para>
|
||||
An invalid #GType, used as error return value in some functions which return
|
||||
An invalid #GType used as error return value in some functions which return
|
||||
a #GType.
|
||||
</para>
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user