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

Documentation tweaks

Browse Source 
Add Since tags, etc.
This commit is contained in:
Matthias Clasen 2011-05-28 21:12:52 -04:00
parent 2df4750ace
commit d35e83d337
4 changed files with 90 additions and 46 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/reference/glib/glib-sections.txt
View File

@ -1943,6 +1943,7 @@ G_UNIX_ERROR
g_unix_open_pipe g_unix_open_pipe
g_unix_signal_source_new g_unix_signal_source_new
g_unix_signal_add_watch_full g_unix_signal_add_watch_full
g_unix_set_fd_nonblocking
</SECTION> </SECTION>

62
glib/gatomic.c
View File

@ -94,8 +94,8 @@
* *
* Gets the current value of @atomic. * Gets the current value of @atomic.
* *
* This call acts as a full compiler and hardware memory barrier (before * This call acts as a full compiler and hardware
* the get). * memory barrier (before the get).
* *
* Returns: the value of the integer * Returns: the value of the integer
* *
@ -114,11 +114,11 @@ gint
* *
* Sets the value of @atomic to @newval. * Sets the value of @atomic to @newval.
* *
* This call acts as a full compiler and hardware memory barrier (after * This call acts as a full compiler and hardware
* the set). * memory barrier (after the set).
* *
* Since: 2.4 * Since: 2.4
**/ */
void void
(g_atomic_int_set) (volatile gint *atomic, (g_atomic_int_set) (volatile gint *atomic,
gint newval) gint newval)
@ -132,6 +132,9 @@ void
* *
* Increments the value of @atomic by 1. * Increments the value of @atomic by 1.
* *
* Think of this operation as an atomic version of
* <literal>{ *@atomic += 1; }</literal>
*
* This call acts as a full compiler and hardware memory barrier. * This call acts as a full compiler and hardware memory barrier.
* *
* Since: 2.4 * Since: 2.4
@ -148,6 +151,9 @@ void
* *
* Decrements the value of @atomic by 1. * Decrements the value of @atomic by 1.
* *
* Think of this operation as an atomic version of
* <literal>{ *@atomic -= 1; return (*@atomic == 0); }</literal>
*
* This call acts as a full compiler and hardware memory barrier. * This call acts as a full compiler and hardware memory barrier.
* *
* Returns: %TRUE if the resultant value is zero * Returns: %TRUE if the resultant value is zero
@ -166,11 +172,14 @@ gboolean
* @oldval: the value to compare with * @oldval: the value to compare with
* @newval: the value to conditionally replace with * @newval: the value to conditionally replace with
* *
* Compares @atomic to @oldval and, if equal, sets it to @newval. If * Compares @atomic to @oldval and, if equal, sets it to @newval.
* @atomic was not equal to @oldval then no change occurs. * If @atomic was not equal to @oldval then no change occurs.
* *
* This compare and exchange is done atomically. * This compare and exchange is done atomically.
* *
* Think of this operation as an atomic version of
* <literal>{ if (*@atomic == @oldval) { *@atomic = @newval; return TRUE; } else return FALSE; }</literal>
*
* This call acts as a full compiler and hardware memory barrier. * This call acts as a full compiler and hardware memory barrier.
* *
* Returns: %TRUE if the exchange took place * Returns: %TRUE if the exchange took place
@ -192,6 +201,9 @@ gboolean
* *
* Atomically adds @val to the value of @atomic. * Atomically adds @val to the value of @atomic.
* *
* Think of this operation as an atomic version of
* <literal>{ tmp = *atomic; *@atomic += @val; return tmp; }</literal>
*
* This call acts as a full compiler and hardware memory barrier. * This call acts as a full compiler and hardware memory barrier.
* *
* Returns: the value of @atomic before the add, signed * Returns: the value of @atomic before the add, signed
@ -215,6 +227,9 @@ gint
* *
* This call acts as a full compiler and hardware memory barrier. * This call acts as a full compiler and hardware memory barrier.
* *
* Think of this operation as an atomic version of
* <literal>{ tmp = *atomic; *@atomic &= @val; return tmp; }</literal>
*
* Returns: the value of @atomic before the operation, unsigned * Returns: the value of @atomic before the operation, unsigned
* *
* Since: 2.30 * Since: 2.30
@ -234,6 +249,9 @@ guint
* Performs an atomic bitwise 'or' of the value of @atomic and @val, * Performs an atomic bitwise 'or' of the value of @atomic and @val,
* storing the result back in @atomic. * storing the result back in @atomic.
* *
* Think of this operation as an atomic version of
* <literal>{ tmp = *atomic; *@atomic |= @val; return tmp; }</literal>
*
* This call acts as a full compiler and hardware memory barrier. * This call acts as a full compiler and hardware memory barrier.
* *
* Returns: the value of @atomic before the operation, unsigned * Returns: the value of @atomic before the operation, unsigned
@ -255,6 +273,9 @@ guint
* Performs an atomic bitwise 'xor' of the value of @atomic and @val, * Performs an atomic bitwise 'xor' of the value of @atomic and @val,
* storing the result back in @atomic. * storing the result back in @atomic.
* *
* Think of this operation as an atomic version of
* <literal>{ tmp = *atomic; *@atomic ^= @val; return tmp; }</literal>
*
* This call acts as a full compiler and hardware memory barrier. * This call acts as a full compiler and hardware memory barrier.
* *
* Returns: the value of @atomic before the operation, unsigned * Returns: the value of @atomic before the operation, unsigned
@ -275,8 +296,8 @@ guint
* *
* Gets the current value of @atomic. * Gets the current value of @atomic.
* *
* This call acts as a full compiler and hardware memory barrier (before * This call acts as a full compiler and hardware
* the get). * memory barrier (before the get).
* *
* Returns: the value of the pointer * Returns: the value of the pointer
* *
@ -295,8 +316,8 @@ gpointer
* *
* Sets the value of @atomic to @newval. * Sets the value of @atomic to @newval.
* *
* This call acts as a full compiler and hardware memory barrier (after * This call acts as a full compiler and hardware
* the set). * memory barrier (after the set).
* *
* Since: 2.4 * Since: 2.4
**/ **/
@ -313,11 +334,14 @@ void
* @oldval: the value to compare with * @oldval: the value to compare with
* @newval: the value to conditionally replace with * @newval: the value to conditionally replace with
* *
* Compares @atomic to @oldval and, if equal, sets it to @newval. If * Compares @atomic to @oldval and, if equal, sets it to @newval.
* @atomic was not equal to @oldval then no change occurs. * If @atomic was not equal to @oldval then no change occurs.
* *
* This compare and exchange is done atomically. * This compare and exchange is done atomically.
* *
* Think of this operation as an atomic version of
* <literal>{ if (*@atomic == @oldval) { *@atomic = @newval; return TRUE; } else return FALSE; }</literal>
*
* This call acts as a full compiler and hardware memory barrier. * This call acts as a full compiler and hardware memory barrier.
* *
* Returns: %TRUE if the exchange took place * Returns: %TRUE if the exchange took place
@ -340,6 +364,9 @@ gboolean
* *
* Atomically adds @val to the value of @atomic. * Atomically adds @val to the value of @atomic.
* *
* Think of this operation as an atomic version of
* <literal>{ tmp = *atomic; *@atomic += @val; return tmp; }</literal>
*
* This call acts as a full compiler and hardware memory barrier. * This call acts as a full compiler and hardware memory barrier.
* *
* Returns: the value of @atomic before the add, signed * Returns: the value of @atomic before the add, signed
@ -361,6 +388,9 @@ gssize
* Performs an atomic bitwise 'and' of the value of @atomic and @val, * Performs an atomic bitwise 'and' of the value of @atomic and @val,
* storing the result back in @atomic. * storing the result back in @atomic.
* *
* Think of this operation as an atomic version of
* <literal>{ tmp = *atomic; *@atomic &= @val; return tmp; }</literal>
*
* This call acts as a full compiler and hardware memory barrier. * This call acts as a full compiler and hardware memory barrier.
* *
* Returns: the value of @atomic before the operation, unsigned * Returns: the value of @atomic before the operation, unsigned
@ -382,6 +412,9 @@ gsize
* Performs an atomic bitwise 'or' of the value of @atomic and @val, * Performs an atomic bitwise 'or' of the value of @atomic and @val,
* storing the result back in @atomic. * storing the result back in @atomic.
* *
* Think of this operation as an atomic version of
* <literal>{ tmp = *atomic; *@atomic |= @val; return tmp; }</literal>
*
* This call acts as a full compiler and hardware memory barrier. * This call acts as a full compiler and hardware memory barrier.
* *
* Returns: the value of @atomic before the operation, unsigned * Returns: the value of @atomic before the operation, unsigned
@ -403,6 +436,9 @@ gsize
* Performs an atomic bitwise 'xor' of the value of @atomic and @val, * Performs an atomic bitwise 'xor' of the value of @atomic and @val,
* storing the result back in @atomic. * storing the result back in @atomic.
* *
* Think of this operation as an atomic version of
* <literal>{ tmp = *atomic; *@atomic ^= @val; return tmp; }</literal>
*
* This call acts as a full compiler and hardware memory barrier. * This call acts as a full compiler and hardware memory barrier.
* *
* Returns: the value of @atomic before the operation, unsigned * Returns: the value of @atomic before the operation, unsigned

53
glib/glib-unix.c
View File

@ -1,7 +1,7 @@
/* GLIB - Library of useful routines for C programming /* GLIB - Library of useful routines for C programming
* Copyright (C) 2011 Red Hat, Inc. * Copyright (C) 2011 Red Hat, Inc.
* *
* glib-unix.c: UNIX specific API wrappers and convenience functions * glib-unix.c: UNIX specific API wrappers and convenience functions
* *
* This library is free software; you can redistribute it and/or * This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public * modify it under the terms of the GNU Lesser General Public
@ -10,7 +10,7 @@
* *
* This library is distributed in the hope that it will be useful, * This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of * but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details. * Lesser General Public License for more details.
* *
* You should have received a copy of the GNU Lesser General Public * You should have received a copy of the GNU Lesser General Public
@ -54,21 +54,21 @@ g_unix_set_error_from_errno (GError **error)
{ {
int saved_errno = errno; int saved_errno = errno;
g_set_error_literal (error, g_set_error_literal (error,
G_UNIX_ERROR, G_UNIX_ERROR,
0, 0,
g_strerror (errno)); g_strerror (errno));
errno = saved_errno; errno = saved_errno;
return FALSE; return FALSE;
} }
static gboolean static gboolean
g_unix_set_error_from_errno_saved (GError **error, g_unix_set_error_from_errno_saved (GError **error,
int saved_errno) int saved_errno)
{ {
g_set_error_literal (error, g_set_error_literal (error,
G_UNIX_ERROR, G_UNIX_ERROR,
0, 0,
g_strerror (saved_errno)); g_strerror (saved_errno));
errno = saved_errno; errno = saved_errno;
return FALSE; return FALSE;
} }
@ -82,11 +82,12 @@ g_unix_set_error_from_errno_saved (GError **error,
* Similar to the UNIX pipe() call, but on modern systems like Linux * Similar to the UNIX pipe() call, but on modern systems like Linux
* uses the pipe2() system call, which atomically creates a pipe with * uses the pipe2() system call, which atomically creates a pipe with
* the configured flags. The only supported flag currently is * the configured flags. The only supported flag currently is
* %FD_CLOEXEC. If for example you want to configure %O_NONBLOCK, that * %FD_CLOEXEC. If for example you want to configure %O_NONBLOCK,
* must still be done separately with fcntl(). * that must still be done separately with fcntl().
* *
* <note>This function does *not* take %O_CLOEXEC, it takes %FD_CLOEXEC as if * <note>This function does *not* take %O_CLOEXEC, it takes
* for fcntl(); these are different on Linux/glibc.</note> * %FD_CLOEXEC as if for fcntl(); these are different on
* Linux/glibc.</note>
* *
* Returns: %TRUE on success, %FALSE if not (and errno will be set). * Returns: %TRUE on success, %FALSE if not (and errno will be set).
* *
@ -94,8 +95,8 @@ g_unix_set_error_from_errno_saved (GError **error,
*/ */
gboolean gboolean
g_unix_open_pipe (int *fds, g_unix_open_pipe (int *fds,
int flags, int flags,
GError **error) GError **error)
{ {
int ecode; int ecode;
@ -148,11 +149,13 @@ g_unix_open_pipe (int *fds,
* on some older ones may use %O_NDELAY. * on some older ones may use %O_NDELAY.
* *
* Returns: %TRUE if successful * Returns: %TRUE if successful
*
* Since: 2.30
*/ */
gboolean gboolean
g_unix_set_fd_nonblocking (gint fd, g_unix_set_fd_nonblocking (gint fd,
gboolean nonblock, gboolean nonblock,
GError **error) GError **error)
{ {
#ifdef F_GETFL #ifdef F_GETFL
glong fcntl_flags; glong fcntl_flags;
@ -196,7 +199,7 @@ g_unix_set_fd_nonblocking (gint fd,
* be monitored. Note that unlike the UNIX default, all sources which * be monitored. Note that unlike the UNIX default, all sources which
* have created a watch will be dispatched, regardless of which * have created a watch will be dispatched, regardless of which
* underlying thread invoked g_unix_signal_create_watch(). * underlying thread invoked g_unix_signal_create_watch().
* *
* For example, an effective use of this function is to handle SIGTERM * For example, an effective use of this function is to handle SIGTERM
* cleanly; flushing any outstanding files, and then calling * cleanly; flushing any outstanding files, and then calling
* g_main_loop_quit (). It is not safe to do any of this a regular * g_main_loop_quit (). It is not safe to do any of this a regular
@ -219,6 +222,8 @@ g_unix_set_fd_nonblocking (gint fd,
* executed. * executed.
* *
* Returns: A newly created #GSource * Returns: A newly created #GSource
*
* Since: 2.30
*/ */
GSource * GSource *
g_unix_signal_source_new (int signum) g_unix_signal_source_new (int signum)
@ -242,13 +247,15 @@ g_unix_signal_source_new (int signum)
* using g_source_remove(). * using g_source_remove().
* *
* Returns: An ID (greater than 0) for the event source * Returns: An ID (greater than 0) for the event source
*
* Since: 2.30
*/ */
guint guint
g_unix_signal_add_watch_full (int signum, g_unix_signal_add_watch_full (int signum,
int priority, int priority,
GSourceFunc handler, GSourceFunc handler,
gpointer user_data, gpointer user_data,
GDestroyNotify notify) GDestroyNotify notify)
{ {
guint id; guint id;
GSource *source; GSource *source;

20
glib/glib-unix.h
View File

@ -57,20 +57,20 @@
GQuark g_unix_error_quark (void); GQuark g_unix_error_quark (void);
gboolean g_unix_open_pipe (gint *fds, gboolean g_unix_open_pipe (gint *fds,
gint flags, gint flags,
GError **error); GError **error);
gboolean g_unix_set_fd_nonblocking (gint fd, gboolean g_unix_set_fd_nonblocking (gint fd,
gboolean nonblock, gboolean nonblock,
GError **error); GError **error);
GSource *g_unix_signal_source_new (gint signum); GSource *g_unix_signal_source_new (gint signum);
guint g_unix_signal_add_watch_full (gint signum, guint g_unix_signal_add_watch_full (gint signum,
gint priority, gint priority,
GSourceFunc handler, GSourceFunc handler,
gpointer user_data, gpointer user_data,
GDestroyNotify notify); GDestroyNotify notify);
#endif #endif