rwlock (Read-Write Locks)

Overview

Reader-writer lock objects.

#include "etcpal/rwlock.h"

Sometimes also referred to as a shared-exclusive lock or multi-reader lock. When implemented to protect a resource, allows multiple "readers" to access the resource at the same time for read-only purposes.

For example:

// Must be initialized before use with etcpal_rwlock_create().
etcpal_rwlock_t lock;
char device_name[DEVICE_NAME_LENGTH];
 
bool get_device_name(char* buffer)
{
  if (etcpal_rwlock_readlock(&lock))
  {
    // Multiple threads can be in this block simultaneously, which is fine.
    strncpy(buffer, device_name, DEVICE_NAME_LENGTH);
    etcpal_rwlock_readunlock(&lock);
    return true;
  }
  else
  {
    return false;
  }
}
 
bool set_device_name(const char* new_name)
{
  if (etcpal_rwlock_writelock(&lock))
  {
    // Only one thread can be in this block at a time. It also locks all threads out of the read
    // lock block above.
    strncpy(device_name, new_name, DEVICE_NAME_LENGTH);
    etcpal_rwlock_writeunlock(&lock);
    return true;
  }
  else
  {
    return false;
  }
}

These are implemented as "write-preferring" reader-writer locks; this means that new readers are blocked from acquiring a read lock if any context is currently waiting for a write lock.

EtcPal read-write locks are typically implemented using multiple OS synchronization constructs under the hood.

Platform	ETCPAL_RWLOCK_HAS_TIMED_LOCK
FreeRTOS	Yes
Linux	No
macOS	No
MQX	Yes
Windows	No
Zephyr	Yes

Macros
#define	ETCPAL_RWLOCK_HAS_TIMED_LOCK   /* platform-defined */
	Whether etcpal_rwlock_timed_readlock() and etcpal_rwlock_timed_writelock() are meaningful on this platform. More...

Typedefs
typedef PLATFORM_DEFINED	etcpal_rwlock_t
	The read-write lock identifier. More...

Functions
bool	etcpal_rwlock_create (etcpal_rwlock_t *id)
	Create a new read-write lock. More...
bool	etcpal_rwlock_readlock (etcpal_rwlock_t *id)
	Access a read-write lock for reading. More...
bool	etcpal_rwlock_try_readlock (etcpal_rwlock_t *id)
	Try to access a read-write lock for reading. More...
bool	etcpal_rwlock_timed_readlock (etcpal_rwlock_t *id, int timeout_ms)
	Try to access a read-write lock for reading, giving up after a timeout. More...
void	etcpal_rwlock_readunlock (etcpal_rwlock_t *id)
	Release a read lock on a read-write lock object. More...
bool	etcpal_rwlock_writelock (etcpal_rwlock_t *id)
	Access a read-write lock for writing. More...
bool	etcpal_rwlock_try_writelock (etcpal_rwlock_t *id)
	Try to access a read-write lock for writing. More...
bool	etcpal_rwlock_timed_writelock (etcpal_rwlock_t *id, int timeout_ms)
	Try to access a read-write lock for writing, giving up after a timeout. More...
void	etcpal_rwlock_writeunlock (etcpal_rwlock_t *id)
	Release a write lock on a read-write lock object. More...
void	etcpal_rwlock_destroy (etcpal_rwlock_t *id)
	Destroy a read-write lock object. More...

Macro Definition Documentation

ETCPAL_RWLOCK_HAS_TIMED_LOCK

#define ETCPAL_RWLOCK_HAS_TIMED_LOCK   /* platform-defined */

Whether etcpal_rwlock_timed_readlock() and etcpal_rwlock_timed_writelock() are meaningful on this platform.

If defined to 0, the etcpal_rwlock_timed_*lock() functions execute the equivalent of etcpal_rwlock_try_*lock() if given a timeout of 0, or etcpal_rwlock_*lock() otherwise.

Typedef Documentation

etcpal_rwlock_t

typedef PLATFORM_DEFINED etcpal_rwlock_t

The read-write lock identifier.

This is highly likely to be a struct.

Function Documentation

etcpal_rwlock_create()

bool etcpal_rwlock_create

(

etcpal_rwlock_t *

id

)

Create a new read-write lock.

Parameters

[out]

id

Read-write lock identifier on which to create a read-write lock. If this function returns true, id becomes valid for calls to other etcpal_rwlock API functions.

Returns

true: The read-write lock was created.

false: The read-write lock was not created.

etcpal_rwlock_destroy()

void etcpal_rwlock_destroy

(

etcpal_rwlock_t *

id

)

Destroy a read-write lock object.

Parameters

[in]

id

Identifier for the read-write lock object to destroy.

etcpal_rwlock_readlock()

bool etcpal_rwlock_readlock

(

etcpal_rwlock_t *

id

)

Access a read-write lock for reading.

Blocks until any write lock has been released. Multiple contexts may have a read lock simultaneously. In typical usage, the resource protected by this lock should only be read, not modified, while inside a read lock.

Parameters

[in]

id

Identifier for the read-write lock on which to acquire a read lock.

Returns

true: The read lock was acquired.

false: The lock is invalid, or an error occurred.

etcpal_rwlock_readunlock()

void etcpal_rwlock_readunlock

(

etcpal_rwlock_t *

id

)

Release a read lock on a read-write lock object.

Parameters

[in]

id

Identifier for the read-write lock on which to release the read lock.

etcpal_rwlock_timed_readlock()

bool etcpal_rwlock_timed_readlock	(	etcpal_rwlock_t *	id,
		int	timeout_ms
	)

Try to access a read-write lock for reading, giving up after a timeout.

This function is not honored on all platforms. The value of ETCPAL_RWLOCK_HAS_TIMED_LOCK can be used to determine whether this function is honored on the current platform. If it is defined to 0, this function executes the equivalent of etcpal_rwlock_try_readlock() if timeout_ms is 0, or etcpal_rwlock_readlock() otherwise.

In typical usage, the resource protected by this lock should only be read, not modified, while inside a read lock.

Parameters

[in]	id	Identifier for the read-write lock on which to acquire a read lock.
[in]	timeout_ms	Maximum amount of time to wait to acquire a read lock, in milliseconds. If ETCPAL_WAIT_FOREVER is given, the result is the same as if etcpal_rwlock_readlock() was called.

Returns

true: The read lock was acquired.

false: The timeout expired, the lock is invalid or an error occurred.

etcpal_rwlock_timed_writelock()

bool etcpal_rwlock_timed_writelock	(	etcpal_rwlock_t *	id,
		int	timeout_ms
	)

Try to access a read-write lock for writing, giving up after a timeout.

This function is not honored on all platforms. The value of ETCPAL_RWLOCK_HAS_TIMED_LOCK can be used to determine whether this function is honored on the current platform. If it is defined to 0, this function executes the equivalent of etcpal_rwlock_try_writelock() if timeout_ms is 0, or etcpal_rwlock_writelock() otherwise.

Parameters

[in]	id	Identifier for the read-write lock on which to acquire a write lock.
[in]	timeout_ms	Maximum amount of time to wait to acquire a write lock, in milliseconds. If ETCPAL_WAIT_FOREVER is given, the result is the same as if etcpal_rwlock_writelock() was called.

Returns

true: The write lock was acquired.

false: The timeout expired, the lock is invalid or an error occurred.

etcpal_rwlock_try_readlock()

bool etcpal_rwlock_try_readlock

(

etcpal_rwlock_t *

id

)

Try to access a read-write lock for reading.

Returns immediately either failure or success; does not block. Fails if a write lock is held from another context. Multiple contexts may have a read lock simultaneously. In typical usage, the resource protected by this lock should only be read, not modified, while inside a read lock.

Parameters

[in]

id

Identifier for the read-write lock on which to acquire a read lock.

Returns

true: The read lock was acquired.

false: The lock was held for writing from another thread, the lock is invalid, or an error occurred.

etcpal_rwlock_try_writelock()

bool etcpal_rwlock_try_writelock

(

etcpal_rwlock_t *

id

)

Try to access a read-write lock for writing.

Returns immediately either failure or success; does not block. Fails if a read or write lock is held from another context.

Parameters

[in]

id

Identifier for the read-write lock on which to acquire a read lock.

Returns

true: The write lock was acquired.

false: The lock was held for reading or writing from another thread, the lock was invalid, or an error occurred.

etcpal_rwlock_writelock()

bool etcpal_rwlock_writelock

(

etcpal_rwlock_t *

id

)

Access a read-write lock for writing.

Blocks until all read and write locks have been released. No new read locks are allowed while this function is being blocked on.

Parameters

[in]

id

Identifier for the read-write lock on which to acquire a write lock.

Returns

true: The write lock was acquired.

false: The lock is invalid, or an error occurred.

etcpal_rwlock_writeunlock()

void etcpal_rwlock_writeunlock

(

etcpal_rwlock_t *

id

)

Release a write lock on a read-write lock object.

Parameters

[in]

id

Identifier for the read-write lock on which to release the write lock.