Class StaticRWLock

java.lang.Object
org.javagi.base.ProxyInstance
org.gnome.glib.StaticRWLock
All Implemented Interfaces:
Proxy
@Generated("org.javagi.JavaGI") @Deprecated public class StaticRWLock extends ProxyInstance
Deprecated.
Use a RWLock instead

The StaticRWLock struct represents a read-write lock. A read-write lock can be used for protecting data that some portions of code only read from, while others also write. In such situations it is desirable that several readers can read at once, whereas of course only one writer may write at a time.

Take a look at the following example:

  GStaticRWLock rwlock = G_STATIC_RW_LOCK_INIT;
  GPtrArray *array;

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

    if (!array)
      return NULL;

    g_static_rw_lock_reader_lock (&rwlock);
    if (index < array->len)
      retval = g_ptr_array_index (array, index);
    g_static_rw_lock_reader_unlock (&rwlock);

    return retval;
  }

  void
  my_array_set (guint index, gpointer data)
  {
    g_static_rw_lock_writer_lock (&rwlock);

    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_static_rw_lock_writer_unlock (&rwlock);
  }

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 once 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.

Most of the time, writers should have precedence over readers. That means, for this implementation, that as soon as a writer wants to lock the data, no other reader is allowed to lock the data, whereas, of course, the readers that already have locked the data are allowed to finish their operation. As soon as the last reader unlocks the data, the writer will lock it.

Even though StaticRWLock is not opaque, it should only be used with the following functions.

All of the g_static_rw_lock_* functions can be used even if Thread.init(MemorySegment) has not been called. Then they do nothing, apart from g_static_rw_lock_*_trylock, which does nothing but returning true.

A read-write lock has a higher overhead than a mutex. For example, both readerLock() and readerUnlock() have to lock and unlock a StaticMutex, so it takes at least twice the time to lock and unlock a StaticRWLock that it does to lock and unlock a StaticMutex. So only data structures that are accessed by multiple readers, and which keep the lock for a considerable time justify a StaticRWLock. The above example most probably would fare better with a StaticMutex.

  • Constructor Summary

    Constructors
    Constructor
    Description
    StaticRWLock()
    Deprecated.
    Allocate a new StaticRWLock.
    StaticRWLock(Arena arena)
    Deprecated.
    Allocate a new StaticRWLock.
    StaticRWLock(MemorySegment address)
    Deprecated.
    Create a StaticRWLock proxy instance for the provided memory address.
    StaticRWLock(StaticMutex mutex, Cond readCond, Cond writeCond, int readCounter, boolean haveWriter, int wantToRead, int wantToWrite)
    Deprecated.
    Allocate a new StaticRWLock with the fields set to the provided values.
    StaticRWLock(StaticMutex mutex, Cond readCond, Cond writeCond, int readCounter, boolean haveWriter, int wantToRead, int wantToWrite, Arena arena)
    Deprecated.
    Allocate a new StaticRWLock with the fields set to the provided values.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    free()
    Deprecated.
    Use a GRWLock instead
    static MemoryLayout
    getMemoryLayout()
    Deprecated.
    The memory layout of the native struct.
    void
    init()
    Deprecated.
    Use g_rw_lock_init() instead
    void
    readerLock()
    Deprecated.
    Use g_rw_lock_reader_lock() instead
    boolean
    readerTrylock()
    Deprecated.
    Use g_rw_lock_reader_trylock() instead
    void
    readerUnlock()
    Deprecated.
    Use g_rw_lock_reader_unlock() instead
    boolean
    readHaveWriter()
    Deprecated.
    Read the value of the field have_writer.
    @Nullable StaticMutex
    readMutex()
    Deprecated.
    Read the value of the field mutex.
    Cond
    readReadCond()
    Deprecated.
    Read the value of the field read_cond.
    int
    readReadCounter()
    Deprecated.
    Read the value of the field read_counter.
    int
    readWantToRead()
    Deprecated.
    Read the value of the field want_to_read.
    int
    readWantToWrite()
    Deprecated.
    Read the value of the field want_to_write.
    Cond
    readWriteCond()
    Deprecated.
    Read the value of the field write_cond.
    void
    writeHaveWriter(boolean haveWriter)
    Deprecated.
    Write a value in the field have_writer.
    void
    writeMutex(@Nullable StaticMutex mutex)
    Deprecated.
    Write a value in the field mutex.
    void
    writeReadCond(Cond readCond)
    Deprecated.
    Write a value in the field read_cond.
    void
    writeReadCounter(int readCounter)
    Deprecated.
    Write a value in the field read_counter.
    void
    writerLock()
    Deprecated.
    Use g_rw_lock_writer_lock() instead
    boolean
    writerTrylock()
    Deprecated.
    Use g_rw_lock_writer_trylock() instead
    void
    writerUnlock()
    Deprecated.
    Use g_rw_lock_writer_unlock() instead
    void
    writeWantToRead(int wantToRead)
    Deprecated.
    Write a value in the field want_to_read.
    void
    writeWantToWrite(int wantToWrite)
    Deprecated.
    Write a value in the field want_to_write.
    void
    writeWriteCond(Cond writeCond)
    Deprecated.
    Write a value in the field write_cond.

    Methods inherited from class ProxyInstance

    equals, handle, hashCode

    Methods inherited from class Object

    clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • StaticRWLock

      public StaticRWLock(MemorySegment address)
      Deprecated.
      Create a StaticRWLock proxy instance for the provided memory address.
      Parameters:
      address - the memory address of the native object

    • StaticRWLock

      public StaticRWLock(Arena arena)
      Deprecated.
      Allocate a new StaticRWLock.
      Parameters:
      arena - to control the memory allocation scope

    • StaticRWLock

      public StaticRWLock()
      Deprecated.
      Allocate a new StaticRWLock. The memory is allocated with Arena.ofAuto().

    • StaticRWLock

      public StaticRWLock(StaticMutex mutex, Cond readCond, Cond writeCond, int readCounter, boolean haveWriter, int wantToRead, int wantToWrite, Arena arena)
      Deprecated.
      Allocate a new StaticRWLock with the fields set to the provided values.
      Parameters:
      mutex - value for the field mutex
      readCond - value for the field readCond
      writeCond - value for the field writeCond
      readCounter - value for the field readCounter
      haveWriter - value for the field haveWriter
      wantToRead - value for the field wantToRead
      wantToWrite - value for the field wantToWrite
      arena - to control the memory allocation scope

    • StaticRWLock

      public StaticRWLock(StaticMutex mutex, Cond readCond, Cond writeCond, int readCounter, boolean haveWriter, int wantToRead, int wantToWrite)
      Deprecated.
      Allocate a new StaticRWLock with the fields set to the provided values. The memory is allocated with Arena.ofAuto().
      Parameters:
      mutex - value for the field mutex
      readCond - value for the field readCond
      writeCond - value for the field writeCond
      readCounter - value for the field readCounter
      haveWriter - value for the field haveWriter
      wantToRead - value for the field wantToRead
      wantToWrite - value for the field wantToWrite

  • Method Details

    • getMemoryLayout

      public static MemoryLayout getMemoryLayout()
      Deprecated.
      The memory layout of the native struct.
      Returns:
      the memory layout

    • readMutex

      public @Nullable StaticMutex readMutex()
      Deprecated.
      Read the value of the field mutex.
      Returns:
      The value of the field mutex

    • writeMutex

      public void writeMutex(@Nullable StaticMutex mutex)
      Deprecated.
      Write a value in the field mutex.
      Parameters:
      mutex - The new value for the field mutex

    • readReadCond

      public Cond readReadCond()
      Deprecated.
      Read the value of the field read_cond.
      Returns:
      The value of the field read_cond

    • writeReadCond

      public void writeReadCond(Cond readCond)
      Deprecated.
      Write a value in the field read_cond.
      Parameters:
      readCond - The new value for the field read_cond

    • readWriteCond

      public Cond readWriteCond()
      Deprecated.
      Read the value of the field write_cond.
      Returns:
      The value of the field write_cond

    • writeWriteCond

      public void writeWriteCond(Cond writeCond)
      Deprecated.
      Write a value in the field write_cond.
      Parameters:
      writeCond - The new value for the field write_cond

    • readReadCounter

      public int readReadCounter()
      Deprecated.
      Read the value of the field read_counter.
      Returns:
      The value of the field read_counter

    • writeReadCounter

      public void writeReadCounter(int readCounter)
      Deprecated.
      Write a value in the field read_counter.
      Parameters:
      readCounter - The new value for the field read_counter

    • readHaveWriter

      public boolean readHaveWriter()
      Deprecated.
      Read the value of the field have_writer.
      Returns:
      The value of the field have_writer

    • writeHaveWriter

      public void writeHaveWriter(boolean haveWriter)
      Deprecated.
      Write a value in the field have_writer.
      Parameters:
      haveWriter - The new value for the field have_writer

    • readWantToRead

      public int readWantToRead()
      Deprecated.
      Read the value of the field want_to_read.
      Returns:
      The value of the field want_to_read

    • writeWantToRead

      public void writeWantToRead(int wantToRead)
      Deprecated.
      Write a value in the field want_to_read.
      Parameters:
      wantToRead - The new value for the field want_to_read

    • readWantToWrite

      public int readWantToWrite()
      Deprecated.
      Read the value of the field want_to_write.
      Returns:
      The value of the field want_to_write

    • writeWantToWrite

      public void writeWantToWrite(int wantToWrite)
      Deprecated.
      Write a value in the field want_to_write.
      Parameters:
      wantToWrite - The new value for the field want_to_write

    • free

      @Deprecated public void free()
      Deprecated.
      Use a GRWLock instead

      Releases all resources allocated to lock.

      You don't have to call this functions for a GStaticRWLock with an unbounded lifetime, i.e. objects declared 'static', but if you have a GStaticRWLock as a member of a structure, and the structure is freed, you should also free the GStaticRWLock.

    • init

      @Deprecated public void init()
      Deprecated.
      Use g_rw_lock_init() instead
      A GStaticRWLock must be initialized with this function before it can be used. Alternatively you can initialize it with G_STATIC_RW_LOCK_INIT.

    • readerLock

      @Deprecated public void readerLock()
      Deprecated.
      Use g_rw_lock_reader_lock() instead

      Locks this StaticRWLock for reading. There may be unlimited concurrent locks for reading of a GStaticRWLock at the same time. If this StaticRWLock is already locked for writing by another thread or if another thread is already waiting to lock this StaticRWLock for writing, this function will block until this StaticRWLock is unlocked by the other writing thread and no other writing threads want to lock lock. This lock has to be unlocked by g_static_rw_lock_reader_unlock().

      GStaticRWLock is not recursive. It might seem to be possible to recursively lock for reading, but that can result in a deadlock, due to writer preference.

    • readerTrylock

      @Deprecated public boolean readerTrylock()
      Deprecated.
      Use g_rw_lock_reader_trylock() instead
      Tries to lock this StaticRWLock for reading. If this StaticRWLock is already locked for writing by another thread or if another thread is already waiting to lock this StaticRWLock for writing, immediately returns false. Otherwise locks this StaticRWLock for reading and returns true. This lock has to be unlocked by g_static_rw_lock_reader_unlock().
      Returns:
      true, if this StaticRWLock could be locked for reading

    • readerUnlock

      @Deprecated public void readerUnlock()
      Deprecated.
      Use g_rw_lock_reader_unlock() instead
      Unlocks lock. If a thread waits to lock this StaticRWLock for writing and all locks for reading have been unlocked, the waiting thread is woken up and can lock this StaticRWLock for writing.

    • writerLock

      @Deprecated public void writerLock()
      Deprecated.
      Use g_rw_lock_writer_lock() instead
      Locks this StaticRWLock for writing. If this StaticRWLock is already locked for writing or reading by other threads, this function will block until this StaticRWLock is completely unlocked and then lock this StaticRWLock for writing. While this functions waits to lock lock, no other thread can lock this StaticRWLock for reading. When this StaticRWLock is locked for writing, no other thread can lock this StaticRWLock (neither for reading nor writing). This lock has to be unlocked by g_static_rw_lock_writer_unlock().

    • writerTrylock

      @Deprecated public boolean writerTrylock()
      Deprecated.
      Use g_rw_lock_writer_trylock() instead
      Tries to lock this StaticRWLock for writing. If this StaticRWLock is already locked (for either reading or writing) by another thread, it immediately returns false. Otherwise it locks this StaticRWLock for writing and returns true. This lock has to be unlocked by g_static_rw_lock_writer_unlock().
      Returns:
      true, if this StaticRWLock could be locked for writing

    • writerUnlock

      @Deprecated public void writerUnlock()
      Deprecated.
      Use g_rw_lock_writer_unlock() instead
      Unlocks lock. If a thread is waiting to lock this StaticRWLock for writing and all locks for reading have been unlocked, the waiting thread is woken up and can lock this StaticRWLock for writing. If no thread is waiting to lock this StaticRWLock for writing, and some thread or threads are waiting to lock this StaticRWLock for reading, the waiting threads are woken up and can lock this StaticRWLock for reading.