GNOME.org
 

[glib/wip/ebassi/rc-new: 79/86] Add reference counting types

commit c3e7ac4179c816b4052ea4b9adafd8711dba4912
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Wed Jan 17 16:38:45 2018 +0000

    Add reference counting types
    
    We have a common pattern for reference counting in GLib, but we always
    implement it with ad hoc code. This is a good chance at trying to
    standardise the implementation and make it public, so that other code
    using GLib can take advantage of shared behaviour and semantics.
    
    Instead of simply taking an integer variable, we should create type
    aliases, to immediately distinguish the reference counting semantics of
    the code; we can handle mixing atomic reference counting with a
    non-atomic type (and vice versa) by using differently signed values for
    the atomic and non-atomic cases.

 docs/reference/glib/glib-docs.xml     |   1 +
 docs/reference/glib/glib-sections.txt |  15 ++
 glib/Makefile.am                      |   2 +
 glib/glib.h                           |   1 +
 glib/grefcount.c                      | 268 ++++++++++++++++++++++++++++++++++
 glib/grefcount.h                      |  51 +++++++
 glib/gtypes.h                         |   3 +
 glib/meson.build                      |   2 +
 8 files changed, 343 insertions(+)
---
diff --git a/docs/reference/glib/glib-docs.xml b/docs/reference/glib/glib-docs.xml
index a0716c172..26cdafb67 100644
--- a/docs/reference/glib/glib-docs.xml
+++ b/docs/reference/glib/glib-docs.xml
@@ -119,6 +119,7 @@
     <xi:include href="xml/gvariant.xml"/>
     <xi:include href="gvariant-varargs.xml"/>
     <xi:include href="gvariant-text.xml"/>
+    <xi:include href="xml/refcount.xml"/>
   </chapter>
 
   <chapter id="deprecated">
diff --git a/docs/reference/glib/glib-sections.txt b/docs/reference/glib/glib-sections.txt
index 2832983ee..711f77766 100644
--- a/docs/reference/glib/glib-sections.txt
+++ b/docs/reference/glib/glib-sections.txt
@@ -3441,3 +3441,18 @@ g_hostname_is_ip_address
 g_uuid_string_is_valid
 g_uuid_string_random
 </SECTION>
+
+<SECTION>
+<FILE>refcount</FILE>
+grefcount
+g_ref_count_init
+g_ref_count_inc
+g_ref_count_dec
+g_ref_count_compare
+<SUBSECTION>
+gatomicrefcount
+g_atomic_ref_count_init
+g_atomic_ref_count_inc
+g_atomic_ref_count_dec
+g_atomic_ref_count_compare
+</SECTION>
diff --git a/glib/Makefile.am b/glib/Makefile.am
index 8da549c7f..6be9d98fc 100644
--- a/glib/Makefile.am
+++ b/glib/Makefile.am
@@ -153,6 +153,7 @@ libglib_2_0_la_SOURCES =    \
        gquark.c                \
        gqueue.c                \
        grand.c                 \
+       grefcount.c             \
        gregex.c                \
        gscanner.c              \
        gscripttable.h          \
@@ -287,6 +288,7 @@ glibsubinclude_HEADERS = \
        gquark.h        \
        gqueue.h        \
        grand.h         \
+       grefcount.h     \
        gregex.h        \
        gscanner.h      \
        gsequence.h     \
diff --git a/glib/glib.h b/glib/glib.h
index 4f5a7f702..84299c4f9 100644
--- a/glib/glib.h
+++ b/glib/glib.h
@@ -69,6 +69,7 @@
 #include <glib/gquark.h>
 #include <glib/gqueue.h>
 #include <glib/grand.h>
+#include <glib/grefcount.h>
 #include <glib/gregex.h>
 #include <glib/gscanner.h>
 #include <glib/gsequence.h>
diff --git a/glib/grefcount.c b/glib/grefcount.c
new file mode 100644
index 000000000..adc83fd82
--- /dev/null
+++ b/glib/grefcount.c
@@ -0,0 +1,268 @@
+/*
+ * Copyright 2018  Emmanuele Bassi
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, see <http://www.gnu.org/licenses/>.
+ */
+
+/**
+ * SECTION:refcount
+ * @Title: Reference counting
+ * @Short_description: Reference counting types and functions
+ *
+ * The #grefcount and #gatomicrefcount types provide simple and atomic
+ * reference counting, respectively.
+ *
+ * You should use these types when implementing reference counting
+ * semantics on a data type. You should initialize the type using
+ * g_ref_count_init() or g_atomic_ref_count_init(); every time you
+ * acquire a reference, you should call g_ref_count_inc() or
+ * g_atomic_ref_count_inc(); and every time you release a reference,
+ * you should call g_ref_count_dec() or g_atomic_ref_count_dec(), and
+ * check the return value to know if it was the last reference held,
+ * and it's time to free the resources associated with your reference
+ * counted data type.
+ *
+ * |[<!-- language="C" -->
+ * // A simple reference counted string data type
+ * typedef struct {
+ *   gatomicrefcount ref_count;
+ *
+ *   char *str;
+ *   int length;
+ * } StringRef;
+ *
+ * StringRef *
+ * string_ref_new (const char *str)
+ * {
+ *   StringRef *ref = g_new0 (StringRef, 1);
+ *
+ *   ref->str = g_strdup (str);
+ *   ref->len = strlen (str);
+ *
+ *   g_atomic_ref_count_init (&ref->ref_count);
+ *
+ *   return ref;
+ * }
+ *
+ * // Acquire a reference on StringRef
+ * StringRef *
+ * string_ref_acquire (StringRef *ref)
+ * {
+ *   g_atomic_ref_count_inc (&ref->ref_count);
+ *   return ref;
+ * }
+ *
+ * // Release a reference on StringRef, and frees the data
+ * // if it's the last reference
+ * void
+ * string_ref_release (StringRef *ref)
+ * {
+ *   if (g_atomic_ref_count_dec (&ref->ref_count))
+ *     {
+ *       g_free (ref->str);
+ *       g_free (ref);
+ *     }
+ * }
+ * ]|
+ */
+
+#include "config.h"
+
+#include "grefcount.h"
+
+#include "gatomic.h"
+#include "gmessages.h"
+
+/**
+ * g_ref_count_init:
+ * @rc: the address of a reference count variable
+ *
+ * Initializes a reference count variable.
+ *
+ * Since: 2.56
+ */
+void
+g_ref_count_init (grefcount *rc)
+{
+  g_return_if_fail (rc != NULL);
+
+  *rc = -1;
+}
+
+/**
+ * g_ref_count_inc:
+ * @rc: the address of a reference count variable
+ *
+ * Increases the reference count.
+ *
+ * Since: 2.56
+ */
+void
+g_ref_count_inc (grefcount *rc)
+{
+  g_return_if_fail (rc != NULL);
+
+  grefcount rrc = *rc;
+
+  g_return_if_fail (rrc < 0);
+
+  rrc -= 1;
+  if (rrc == G_MININT)
+    {
+      g_critical ("Reference counter %p is saturated", rc);
+      return;
+    }
+
+  *rc = rrc;
+}
+
+/**
+ * g_ref_count_dec:
+ * @rc: the address of a reference count variable
+ *
+ * Decreases the reference count.
+ *
+ * Returns: %TRUE if the reference count reached 0, and %FALSE otherwise
+ *
+ * Since: 2.56
+ */
+gboolean
+g_ref_count_dec (grefcount *rc)
+{
+  g_return_val_if_fail (rc != NULL, FALSE);
+
+  grefcount rrc = *rc;
+  g_return_val_if_fail (rrc < 0, FALSE);
+
+  rrc += 1;
+
+  *rc = rrc;
+
+  if (rrc == 0)
+    return TRUE;
+
+  return FALSE;
+}
+
+/**
+ * g_ref_count_compare:
+ * @rc: the address of a reference count variable
+ * @val: the value to compare
+ *
+ * Compares the current value of @rc with @val.
+ *
+ * Returns: %TRUE if the reference count is the same
+ *   as the given value
+ *
+ * Since: 2.56
+ */
+gboolean
+g_ref_count_compare (grefcount *rc,
+                     gint       val)
+{
+  g_return_val_if_fail (rc != NULL, FALSE);
+
+  grefcount rrc = *rc;
+
+  return rrc == -val;
+}
+
+/**
+ * g_atomic_ref_count_init:
+ * @arc: the address of an atomic reference count variable
+ *
+ * Atomically initializes a reference count variable.
+ *
+ * Since: 2.56
+ */
+void
+g_atomic_ref_count_init (gatomicrefcount *arc)
+{
+  g_return_if_fail (arc != NULL);
+
+  g_atomic_int_set (arc, 1);
+}
+
+/**
+ * g_atomic_ref_count_inc:
+ * @arc: the address of an atomic reference count variable
+ *
+ * Atomically increases the reference count.
+ *
+ * Since: 2.56
+ */
+void
+g_atomic_ref_count_inc (gatomicrefcount *arc)
+{
+  gatomicrefcount rc;
+
+  g_return_if_fail (arc != NULL);
+
+  rc = g_atomic_int_get (arc);
+  g_return_if_fail (rc > 0);
+
+  while (TRUE)
+    {
+      gatomicrefcount new = rc + 1;
+
+      if (new == G_MAXINT)
+        {
+          g_critical ("Atomic reference counter %p is saturated", arc);
+          return;
+        }
+
+      if (g_atomic_int_compare_and_exchange (arc, rc, new))
+        break;
+   }
+}
+
+/**
+ * g_atomic_ref_count_dec:
+ * @arc: the address of an atomic reference count variable
+ *
+ * Atomically decreases the reference count.
+ *
+ * Returns: %TRUE if the reference count reached 0, and %FALSE otherwise
+ *
+ * Since: 2.56
+ */
+gboolean
+g_atomic_ref_count_dec (gatomicrefcount *arc)
+{
+  g_return_val_if_fail (arc != NULL, FALSE);
+  g_return_val_if_fail (g_atomic_int_get (arc) > 0, FALSE);
+
+  return g_atomic_int_dec_and_test (arc);
+}
+
+/**
+ * g_atomic_ref_count_compare:
+ * @arc: the address of an atomic reference count variable
+ * @val: the value to compare
+ *
+ * Atomically compares the current value of @arc with @val.
+ *
+ * Returns: %TRUE if the reference count is the same
+ *   as the given value
+ *
+ * Since: 2.56
+ */
+gboolean
+g_atomic_ref_count_compare (gatomicrefcount *arc,
+                            gint             val)
+{
+  g_return_val_if_fail (arc != NULL, FALSE);
+
+  return g_atomic_int_get (arc) == val;
+}
diff --git a/glib/grefcount.h b/glib/grefcount.h
new file mode 100644
index 000000000..61b4d6aa9
--- /dev/null
+++ b/glib/grefcount.h
@@ -0,0 +1,51 @@
+/*
+ * Copyright 2018  Emmanuele Bassi
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, see <http://www.gnu.org/licenses/>.
+ */
+
+#ifndef __GREFCOUNT_H__
+#define __GREFCOUNT_H__
+
+#if !defined (__GLIB_H_INSIDE__) && !defined (GLIB_COMPILATION)
+#error "Only <glib.h> can be included directly."
+#endif
+
+#include <glib/gtypes.h>
+
+G_BEGIN_DECLS
+
+GLIB_AVAILABLE_IN_2_56
+void            g_ref_count_init                (grefcount       *rc);
+GLIB_AVAILABLE_IN_2_56
+void            g_ref_count_inc                 (grefcount       *rc);
+GLIB_AVAILABLE_IN_2_56
+gboolean        g_ref_count_dec                 (grefcount       *rc);
+GLIB_AVAILABLE_IN_2_56
+gboolean        g_ref_count_compare             (grefcount       *rc,
+                                                 gint             val);
+
+GLIB_AVAILABLE_IN_2_56
+void            g_atomic_ref_count_init         (gatomicrefcount *arc);
+GLIB_AVAILABLE_IN_2_56
+void            g_atomic_ref_count_inc          (gatomicrefcount *arc);
+GLIB_AVAILABLE_IN_2_56
+gboolean        g_atomic_ref_count_dec          (gatomicrefcount *arc);
+GLIB_AVAILABLE_IN_2_56
+gboolean        g_atomic_ref_count_compare      (gatomicrefcount *arc,
+                                                 gint             val);
+
+G_END_DECLS
+
+#endif /* __GREFCOUNT_H__ */
diff --git a/glib/gtypes.h b/glib/gtypes.h
index 047ac6227..e0a3283da 100644
--- a/glib/gtypes.h
+++ b/glib/gtypes.h
@@ -510,6 +510,9 @@ struct _GTimeVal
   glong tv_usec;
 };
 
+typedef gint            grefcount;
+typedef volatile gint   gatomicrefcount;
+
 G_END_DECLS
 
 /* We prefix variable declarations so they can
diff --git a/glib/meson.build b/glib/meson.build
index add29d06e..8797e3c20 100644
--- a/glib/meson.build
+++ b/glib/meson.build
@@ -76,6 +76,7 @@ glib_sub_headers = files(
   'gquark.h',
   'gqueue.h',
   'grand.h',
+  'grefcount.h',
   'gregex.h',
   'gscanner.h',
   'gsequence.h',
@@ -159,6 +160,7 @@ glib_sources = files(
   'gquark.c',
   'gqueue.c',
   'grand.c',
+  'grefcount.c',
   'gregex.c',
   'gscanner.c',
   'gsequence.c',
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]