GLib.RWLock
Description: Reference for GLib.RWLock

### Struct

# GLibRWLock

since: 2.32

#### Description [src]

    struct GRWLock {
      /* No available fields */
    }

The GRWLock struct is an opaque data structure to represent a reader-writer lock. It is similar to a `GMutex` in that it allows multiple threads to coordinate access to a shared resource.

The difference to a mutex is that a reader-writer lock discriminates between read-only (‘reader’) and full (‘writer’) access. While only one thread at a time is allowed write access (by holding the ‘writer’ lock via g_rw_lock_writer_lock()), multiple threads can gain simultaneous read-only access (by holding the ‘reader’ lock via g_rw_lock_reader_lock()).

It is unspecified whether readers or writers have priority in acquiring the lock when a reader already holds the lock and a writer is queued to acquire it.

Here is an example for an array with access functions:

      GRWLock lock;
      GPtrArray *array;

      gpointer
      my_array_get (guint index)
      {
        gpointer retval = NULL;

        if (!array)
          return NULL;

        g_rw_lock_reader_lock (&lock);
        if (index < array->len)
          retval = g_ptr_array_index (array, index);
        g_rw_lock_reader_unlock (&lock);

        return retval;
      }

      void
      my_array_set (guint index, gpointer data)
      {
        g_rw_lock_writer_lock (&lock);

        if (!array)
          array = g_ptr_array_new ();

        if (index >= array->len)
          g_ptr_array_set_size (array, index+1);
        g_ptr_array_index (array, index) = data;

        g_rw_lock_writer_unlock (&lock);
      }

This example shows an array which can be accessed by many readers (the `my_array_get()` function) simultaneously, whereas the writers (the `my_array_set()` function) will only be allowed one at a time and only if no readers currently access the array. This is because of the potentially dangerous resizing of the array. Using these functions is fully multi-thread safe now.

If a `GRWLock` is allocated in static storage then it can be used without initialisation. Otherwise, you should call `g_rw_lock_init()` on it and `g_rw_lock_clear()` when done.

A GRWLock should only be accessed with the g_rw_lock_ functions.

Available since: 2.32

#### Instance methods

###### g_rw_lock_clear

Frees the resources allocated to a lock with g_rw_lock_init().

since: 2.32

###### g_rw_lock_init

Initializes a `GRWLock` so that it can be used.

since: 2.32

###### g_rw_lock_reader_lock

Obtain a read lock on `rw_lock`. If another thread currently holds the write lock on `rw_lock`, the current thread will block until the write lock was (held and) released. If another thread does not hold the write lock, but is waiting for it, it is implementation defined whether the reader or writer will block. Read locks can be taken recursively.

since: 2.32

###### g_rw_lock_reader_trylock

Tries to obtain a read lock on `rw_lock` and returns `TRUE` if the read lock was successfully obtained. Otherwise it returns `FALSE`.

since: 2.32

###### g_rw_lock_reader_unlock

Release a read lock on `rw_lock`.

since: 2.32

###### g_rw_lock_writer_lock

Obtain a write lock on `rw_lock`. If another thread currently holds a read or write lock on `rw_lock`, the current thread will block until all other threads have dropped their locks on `rw_lock`.

since: 2.32

###### g_rw_lock_writer_trylock

Tries to obtain a write lock on `rw_lock`. If another thread currently holds a read or write lock on `rw_lock`, it immediately returns `FALSE`. Otherwise it locks `rw_lock` and returns `TRUE`.

since: 2.32

###### g_rw_lock_writer_unlock

Release a write lock on `rw_lock`.

since: 2.32