Reference counting: GLib Reference Manual

## Reference counting Reference counting — Reference counting types and functions |

## Functions

void | g_ref_count_init ()
void | g_ref_count_inc ()
gboolean | g_ref_count_dec ()
gboolean | g_ref_count_compare ()
void | g_atomic_ref_count_init ()
void | g_atomic_ref_count_inc ()
gboolean | g_atomic_ref_count_dec ()
gboolean | g_atomic_ref_count_compare ()

## Types and Values

typedef | grefcount
#define | G_REF_COUNT_INIT
typedef | gatomicrefcount
#define | G_ATOMIC_REF_COUNT_INIT

## 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

### G_REF_COUNT_INIT

    #define             G_REF_COUNT_INIT

Evaluates to the initial reference count for `grefcount`.

This macro is useful for initializing `grefcount` fields inside structures, for instance:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    typedef struct {
      grefcount ref_count;
      char *name;
      char *address;
    } Person;

    static const Person default_person = {
      .ref_count = G_REF_COUNT_INIT,
      .name = "Default name",
      .address = "Default address",
    };

Since: 2.78

### 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

### G_ATOMIC_REF_COUNT_INIT

    #define             G_ATOMIC_REF_COUNT_INIT

Evaluates to the initial reference count for `gatomicrefcount`.

This macro is useful for initializing `gatomicrefcount` fields inside structures, for instance:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    typedef struct {
      gatomicrefcount ref_count;
      char *name;
      char *address;
    } Person;

    static const Person default_person = {
      .ref_count = G_ATOMIC_REF_COUNT_INIT,
      .name = "Default name",
      .address = "Default address",
    };

Since: 2.78