GLib.RWLock

Fields

Name	Type	Access	Description
i	[int]	r
p	object	r

Methods

	clear ()
	init ()
	reader_lock ()
	reader_trylock ()
	reader_unlock ()
	writer_lock ()
	writer_trylock ()
	writer_unlock ()

Details

class GLib.RWLock

The GLib.RWLock struct is an opaque data structure to represent a reader-writer lock. It is similar to a GLib.Mutex 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 GLib.RWLock.writer_lock()), multiple threads can gain simultaneous read-only access (by holding the ‘reader’ lock via GLib.RWLock.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 GLib.RWLock is allocated in static storage then it can be used without initialisation. Otherwise, you should call GLib.RWLock.init() on it and GLib.RWLock.clear() when done.

A GLib.RWLock should only be accessed with the g_rw_lock_ functions.

New in version 2.32.

clear()

Frees the resources allocated to a lock with GLib.RWLock.init().

This function should not be used with a GLib.RWLock that has been statically allocated.

Calling GLib.RWLock.clear() when any thread holds the lock leads to undefined behaviour.

Sine: 2.32

init()

Initializes a GLib.RWLock so that it can be used.

This function is useful to initialize a lock that has been allocated on the stack, or as part of a larger structure. It is not necessary to initialise a reader-writer lock that has been statically allocated.

typedef struct {
    GRWLock l;
    ...
  } Blob;

Blob *b;

b = g_new (Blob, 1);
g_rw_lock_init (&b->l);

To undo the effect of GLib.RWLock.init() when a lock is no longer needed, use GLib.RWLock.clear().

Calling GLib.RWLock.init() on an already initialized GLib.RWLock leads to undefined behaviour.

New in version 2.32.

reader_lock()

Obtain a read lock on self. If another thread currently holds the write lock on self, the current thread will block. 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.

It is implementation-defined how many threads are allowed to hold read locks on the same lock simultaneously. If the limit is hit, or if a deadlock is detected, a critical warning will be emitted.

New in version 2.32.

reader_trylock()

Returns:True if self could be locked Return type:bool

Tries to obtain a read lock on self and returns True if the read lock was successfully obtained. Otherwise it returns False.

New in version 2.32.

reader_unlock()

Release a read lock on self.

Calling GLib.RWLock.reader_unlock() on a lock that is not held by the current thread leads to undefined behaviour.

New in version 2.32.

writer_lock()

Obtain a write lock on self. If any thread already holds a read or write lock on self, the current thread will block until all other threads have dropped their locks on self.

New in version 2.32.

writer_trylock()

Returns:True if self could be locked Return type:bool

Tries to obtain a write lock on self. If any other thread holds a read or write lock on self, it immediately returns False. Otherwise it locks self and returns True.

New in version 2.32.

writer_unlock()

Release a write lock on self.

Calling GLib.RWLock.writer_unlock() on a lock that is not held by the current thread leads to undefined behaviour.

New in version 2.32.