From c850d25d679a4ee98c9aac3c8f70a833749293e3 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Wed, 15 Nov 2023 14:14:12 +0000 Subject: [PATCH] docs: Move the gatomic SECTION Move it to a standalone page. Signed-off-by: Philip Withnall Helps: #3037 --- docs/reference/glib/atomic.md | 75 ++++++++++++++++++++++++++++++++ docs/reference/glib/glib.toml.in | 1 + docs/reference/glib/meson.build | 1 + glib/gatomic.c | 43 ------------------ 4 files changed, 77 insertions(+), 43 deletions(-) create mode 100644 docs/reference/glib/atomic.md diff --git a/docs/reference/glib/atomic.md b/docs/reference/glib/atomic.md new file mode 100644 index 000000000..65337fe64 --- /dev/null +++ b/docs/reference/glib/atomic.md @@ -0,0 +1,75 @@ +Title: Atomic Operations +SPDX-License-Identifier: LGPL-2.1-or-later +SPDX-FileCopyrightText: 2012 Dan Winship + +# Atomic Operations + +The following is a collection of compiler macros to provide atomic +access to integer and pointer-sized values. + +The macros that have ‘int’ in the name will operate on pointers to `gint` and +`guint`. The macros with ‘pointer’ in the name will operate on pointers to any +pointer-sized value, including `guintptr`. + +There is no support for 64-bit operations on platforms with 32-bit pointers +because it is not generally possible to perform these operations atomically. + +The get, set and exchange operations for integers and pointers +nominally operate on `gint` and `gpointer`, respectively. Of the +arithmetic operations, the ‘add’ operation operates on (and returns) +signed integer values (`gint` and `gssize`) and the ‘and’, ‘or’, and +‘xor’ operations operate on (and return) unsigned integer values +(`guint` and `gsize`). + +All of the operations act as a full compiler and (where appropriate) +hardware memory barrier. Acquire and release or producer and +consumer barrier semantics are not available through this API. + +It is very important that all accesses to a particular integer or +pointer be performed using only this API and that different sizes of +operation are not mixed or used on overlapping memory regions. Never +read or assign directly from or to a value — always use this API. + +For simple reference counting purposes you should use `gatomicrefcount` +(see [func@GLib.atomic_ref_count_init]) rather than [func@GLib.atomic_int_inc] +and [func@GLib.atomic_int_dec_and_test]. + +Uses of [func@GLib.atomic_int_inc] and [func@GLib.atomic_int_dec_and_test] +that fall outside of simple counting patterns are prone to +subtle bugs and occasionally undefined behaviour. It is also worth +noting that since all of these operations require global +synchronisation of the entire machine, they can be quite slow. In +the case of performing multiple atomic operations it can often be +faster to simply acquire a mutex lock around the critical area, +perform the operations normally and then release the lock. + +## Atomic Integer Operations + + * [func@GLib.atomic_int_get] + * [func@GLib.atomic_int_set] + * [func@GLib.atomic_int_inc] + * [func@GLib.atomic_int_dec_and_test] + * [func@GLib.atomic_int_compare_and_exchange] + * [func@GLib.atomic_int_compare_and_exchange_full] + * [func@GLib.atomic_int_exchange] + * [func@GLib.atomic_int_add] + * [func@GLib.atomic_int_and] + * [func@GLib.atomic_int_or] + * [func@GLib.atomic_int_xor] + +## Atomic Pointer Operations + + * [func@GLib.atomic_pointer_get] + * [func@GLib.atomic_pointer_set] + * [func@GLib.atomic_pointer_compare_and_exchange] + * [func@GLib.atomic_pointer_compare_and_exchange_full] + * [func@GLib.atomic_pointer_exchange] + * [func@GLib.atomic_pointer_add] + * [func@GLib.atomic_pointer_and] + * [func@GLib.atomic_pointer_or] + * [func@GLib.atomic_pointer_xor] + +## Deprecated API + + * [func@GLib.atomic_int_exchange_and_add] + diff --git a/docs/reference/glib/glib.toml.in b/docs/reference/glib/glib.toml.in index 913d6ce73..bd3d97e9e 100644 --- a/docs/reference/glib/glib.toml.in +++ b/docs/reference/glib/glib.toml.in @@ -61,6 +61,7 @@ content_files = [ "main-loop.md", "reference-counting.md", "testing.md", + "atomic.md", "threads.md", "markup.md", "base64.md", diff --git a/docs/reference/glib/meson.build b/docs/reference/glib/meson.build index bb848454b..ff496d72a 100644 --- a/docs/reference/glib/meson.build +++ b/docs/reference/glib/meson.build @@ -145,6 +145,7 @@ endif # gi-docgen version expand_content_files = [ + 'atomic.md', 'base64.md', 'building.md', 'character-set.md', diff --git a/glib/gatomic.c b/glib/gatomic.c index a40885d92..2d3755e68 100644 --- a/glib/gatomic.c +++ b/glib/gatomic.c @@ -23,49 +23,6 @@ #include "gatomic.h" -/** - * SECTION:atomic_operations - * @title: Atomic Operations - * @short_description: basic atomic integer and pointer operations - * @see_also: #GMutex - * - * The following is a collection of compiler macros to provide atomic - * access to integer and pointer-sized values. - * - * The macros that have 'int' in the name will operate on pointers to - * #gint and #guint. The macros with 'pointer' in the name will operate - * on pointers to any pointer-sized value, including #guintptr. There is - * no support for 64bit operations on platforms with 32bit pointers - * because it is not generally possible to perform these operations - * atomically. - * - * The get, set and exchange operations for integers and pointers - * nominally operate on #gint and #gpointer, respectively. Of the - * arithmetic operations, the 'add' operation operates on (and returns) - * signed integer values (#gint and #gssize) and the 'and', 'or', and - * 'xor' operations operate on (and return) unsigned integer values - * (#guint and #gsize). - * - * All of the operations act as a full compiler and (where appropriate) - * hardware memory barrier. Acquire and release or producer and - * consumer barrier semantics are not available through this API. - * - * It is very important that all accesses to a particular integer or - * pointer be performed using only this API and that different sizes of - * operation are not mixed or used on overlapping memory regions. Never - * read or assign directly from or to a value -- always use this API. - * - * For simple reference counting purposes you should use - * g_atomic_int_inc() and g_atomic_int_dec_and_test(). Other uses that - * fall outside of simple reference counting patterns are prone to - * subtle bugs and occasionally undefined behaviour. It is also worth - * noting that since all of these operations require global - * synchronisation of the entire machine, they can be quite slow. In - * the case of performing multiple atomic operations it can often be - * faster to simply acquire a mutex lock around the critical area, - * perform the operations normally and then release the lock. - **/ - /** * G_ATOMIC_LOCK_FREE: *