EtcPal  0.4.1
ETC Platform Abstraction Layer (EtcPal)
View other versions:
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().
char device_name[DEVICE_NAME_LENGTH];
bool get_device_name(char* buffer)
{
{
// Multiple threads can be in this block simultaneously, which is fine.
strncpy(buffer, device_name, DEVICE_NAME_LENGTH);
return true;
}
else
{
return false;
}
}
bool set_device_name(const char* new_name)
{
{
// 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);
return true;
}
else
{
return false;
}
}
void etcpal_rwlock_readunlock(etcpal_rwlock_t *id)
Release a read lock on a read-write lock object.
PLATFORM_DEFINED etcpal_rwlock_t
The read-write lock identifier.
Definition: rwlock.dox:78
void etcpal_rwlock_writeunlock(etcpal_rwlock_t *id)
Release a write lock on a read-write lock object.
bool etcpal_rwlock_readlock(etcpal_rwlock_t *id)
Access a read-write lock for reading.
bool etcpal_rwlock_writelock(etcpal_rwlock_t *id)
Access a read-write lock for writing.

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

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]idRead-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]idIdentifier 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]idIdentifier 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]idIdentifier 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]idIdentifier for the read-write lock on which to acquire a read lock.
[in]timeout_msMaximum 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]idIdentifier for the read-write lock on which to acquire a write lock.
[in]timeout_msMaximum 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]idIdentifier 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]idIdentifier 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]idIdentifier 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]idIdentifier for the read-write lock on which to release the write lock.