Reference counting

Reference counting — Reference counting types and functions

Functions

Types and Values

typedef grefcount
typedef gatomicrefcount

Includes

#include <glib.h>
#include <glib/gi18n.h>

Description

Reference counting is a garbage collection mechanism that is based on assigning a counter to a data type, or any memory area; the counter is increased whenever a new reference to that data type is acquired, and decreased whenever the reference is released. Once the last reference is released, the resources associated to that data type are freed.

GLib uses reference counting in many of its data types, and provides the grefcount and gatomicrefcount types to implement safe and atomic reference counting semantics in new data types.

It is important to note that grefcount and gatomicrefcount should be considered completely opaque types; you should always use the provided API to increase and decrease the counters, and you should never check their content directly, or compare their content with other values.

Functions

g_ref_count_init ()

void
g_ref_count_init (grefcount *rc);

Initializes a reference count variable to 1.

Parameters

rc

the address of a reference count variable

 

Since: 2.58


g_ref_count_inc ()

void
g_ref_count_inc (grefcount *rc);

Increases the reference count.

Parameters

rc

the address of a reference count variable

 

Since: 2.58


g_ref_count_dec ()

gboolean
g_ref_count_dec (grefcount *rc);

Decreases the reference count.

If TRUE is returned, the reference count reached 0. After this point, rc is an undefined state and must be reinitialized with g_ref_count_init() to be used again.

Parameters

rc

the address of a reference count variable

 

Returns

TRUE if the reference count reached 0, and FALSE otherwise

Since: 2.58


g_ref_count_compare ()

gboolean
g_ref_count_compare (grefcount *rc,
                     gint val);

Compares the current value of rc with val .

Parameters

rc

the address of a reference count variable

 

val

the value to compare

 

Returns

TRUE if the reference count is the same as the given value

Since: 2.58


g_atomic_ref_count_init ()

void
g_atomic_ref_count_init (gatomicrefcount *arc);

Initializes a reference count variable to 1.

Parameters

arc

the address of an atomic reference count variable

 

Since: 2.58


g_atomic_ref_count_inc ()

void
g_atomic_ref_count_inc (gatomicrefcount *arc);

Atomically increases the reference count.

Parameters

arc

the address of an atomic reference count variable

 

Since: 2.58


g_atomic_ref_count_dec ()

gboolean
g_atomic_ref_count_dec (gatomicrefcount *arc);

Atomically decreases the reference count.

If TRUE is returned, the reference count reached 0. After this point, arc is an undefined state and must be reinitialized with g_atomic_ref_count_init() to be used again.

Parameters

arc

the address of an atomic reference count variable

 

Returns

TRUE if the reference count reached 0, and FALSE otherwise

Since: 2.58


g_atomic_ref_count_compare ()

gboolean
g_atomic_ref_count_compare (gatomicrefcount *arc,
                            gint val);

Atomically compares the current value of arc with val .

Parameters

arc

the address of an atomic reference count variable

 

val

the value to compare

 

Returns

TRUE if the reference count is the same as the given value

Since: 2.58

Types and Values

grefcount

typedef gint grefcount;

A type for implementing non-atomic reference count semantics.

Use g_ref_count_init() to initialize it; g_ref_count_inc() to increase the counter, and g_ref_count_dec() to decrease it.

It is safe to use grefcount only if you're expecting to operate on the reference counter from a single thread. It is entirely up to you to ensure that all reference count changes happen in the same thread.

See also: gatomicrefcount

Since: 2.58


gatomicrefcount

typedef gint gatomicrefcount;  /* should be accessed only using atomics */

A type for implementing atomic reference count semantics.

Use g_atomic_ref_count_init() to initialize it; g_atomic_ref_count_inc() to increase the counter, and g_atomic_ref_count_dec() to decrease it.

It is safe to use gatomicrefcount if you're expecting to operate on the reference counter from multiple threads.

See also: grefcount

Since: 2.58