ARGOBOTS  1.1
Typedefs | Functions
Readers-Writer Lock

A Readers writer lock allows concurrent access for readers and exclusionary access for writers. More...

Typedefs

typedef struct ABT_rwlock_opaque * ABT_rwlock
 Readers-writer lock handle type. More...
 

Functions

int ABT_rwlock_create (ABT_rwlock *newrwlock)
 Create a new readers-writer lock. More...
 
int ABT_rwlock_free (ABT_rwlock *rwlock)
 Free a readers-writer lock. More...
 
int ABT_rwlock_rdlock (ABT_rwlock rwlock)
 Lock a readers-writer lock as a reader. More...
 
int ABT_rwlock_wrlock (ABT_rwlock rwlock)
 Lock a readers-writer lock as a writer. More...
 
int ABT_rwlock_unlock (ABT_rwlock rwlock)
 Unlock a readers-writer lock. More...
 

Detailed Description

A Readers writer lock allows concurrent access for readers and exclusionary access for writers.

Typedef Documentation

◆ ABT_rwlock

typedef struct ABT_rwlock_opaque* ABT_rwlock

Readers-writer lock handle type.

A NULL handle of this type is ABT_RWLOCK_NULL.

Definition at line 966 of file abt.h.

Function Documentation

◆ ABT_rwlock_create()

int ABT_rwlock_create ( ABT_rwlock newrwlock)

Create a new readers-writer lock.

ABT_rwlock_create() creates a new readers-writer lock and returns its handle through newrwlock.

newrwlock must be freed by ABT_rwlock_free() after its use.

Changes from Argobots 1.x to Argobots 2.0 (planned)
[Argobots 1.x] newrwlock is set to ABT_RWLOCK_NULL if an error occurs.
[Argobots 2.0] newrwlock is not updated if an error occurs.
Rationale
To ensure the atomicity of the API, Argobots 2.0 guarantees that the routine has no effect when an error is returned unless otherwise noted. Argobots 2.0 does not update newrwlock when an error occurs.
Execution context
This routine can be called in any execution context. Argobots must be initialized. This routine does not switch the context of the calling ULT unless any user-defined function that is involved in this routine switch the context of the calling ULT.
Errors
ABT_SUCCESS is returned if this routine succeeds.
ABT_ERR_MEM is returned if memory allocation fails.
ABT_ERR_SYS is returned if an error related to system calls and standard libraries occurs.
Undefined behavior
If Argobots is not initialized, the results are undefined.
If newrwlock is NULL, the results are undefined.
Parameters
[out]newrwlockreaders-writer lock handle
Returns
Error code

Definition at line 40 of file rwlock.c.

◆ ABT_rwlock_free()

int ABT_rwlock_free ( ABT_rwlock rwlock)

Free a readers-writer lock.

ABT_rwlock_free() deallocates the resource used for the readers-writer lock rwlock and sets rwlock to ABT_RWLOCK_NULL.

Note
This routine frees rwlock regardless of whether it is locked or not.
Execution context
This routine can be called in any execution context. Argobots must be initialized. This routine does not switch the context of the calling ULT unless any user-defined function that is involved in this routine switch the context of the calling ULT.
Errors
ABT_SUCCESS is returned if this routine succeeds.
ABT_ERR_INV_RWLOCK is returned if rwlock points to ABT_RWLOCK_NULL.
Undefined behavior
If Argobots is not initialized, the results are undefined.
If rwlock is NULL, the results are undefined.
If there is a waiter blocked on rwlock, the results are undefined.
If rwlock is accessed after calling this routine, the results are undefined.
Parameters
[in,out]rwlockreaders-writer lock handle
Returns
Error code

Definition at line 87 of file rwlock.c.

◆ ABT_rwlock_rdlock()

int ABT_rwlock_rdlock ( ABT_rwlock  rwlock)

Lock a readers-writer lock as a reader.

ABT_rwlock_rdlock() locks the readers-writer lock rwlock as a reader. If this routine successfully returns, the caller acquires rwlock. If rwlock has been locked by a writer, the caller is blocked on rwlock until rwlock becomes available.

rwlock may be acquired by multiple readers.

Note
If rwlock is locked by multiple readers, ABT_rwlock_unlock() must be called as many as the number of readers (i.e., the number of calls of ABT_rwlock_rdlock()) to make rwlock available to a writer.
Changes from Argobots 1.x to Argobots 2.0 (planned)
[Argobots 1.x] If a tasklet calls this routine, ABT_ERR_RWLOCK is returned.
[Argobots 2.0] A tasklet may call this routine.
Rationale
Argobots 2.0 integrates a ULT and a tasklet into a single thread concept to make the API more general.
Execution context
[Argobots 1.x] This routine can be called in a ULT context or an external thread context. Argobots must be initialized. This routine may switch the context of the calling ULT if rwlock is locked by a writer. Otherwise, this routine does not switch the context of the calling ULT unless any user-defined function that is involved in this routine switch the context of the calling ULT.
[Argobots 2.0] This routine can be called in any execution context. Argobots must be initialized. This routine may switch the context of the calling ULT if rwlock is locked by a writer. Otherwise, this routine does not switch the context of the calling ULT unless any user-defined function that is involved in this routine switch the context of the calling ULT.
Errors
ABT_SUCCESS is returned if this routine succeeds.
ABT_ERR_INV_RWLOCK is returned if rwlock is ABT_RWLOCK_NULL.
[Argobots 1.x] ABT_ERR_RWLOCK is returned if the caller is a tasklet.
Undefined behavior
If Argobots is not initialized, the results are undefined.
Parameters
[in]rwlockreaders-writer lock handle
Returns
Error code

Definition at line 138 of file rwlock.c.

◆ ABT_rwlock_unlock()

int ABT_rwlock_unlock ( ABT_rwlock  rwlock)

Unlock a readers-writer lock.

ABT_rwlock_unlock() unlocks the readers-writer lock rwlock.

Note
Both readers and a writer can call this routine to unlock rwlock.
Execution context
This routine can be called in any execution context. Argobots must be initialized. This routine may switch the context of the calling ULT if a waiter is waiting on mutex. Otherwise, this routine does not switch the context of the calling ULT unless any user-defined function that is involved in this routine switch the context of the calling ULT.
Errors
ABT_SUCCESS is returned if this routine succeeds.
ABT_ERR_INV_RWLOCK is returned if rwlock is ABT_RWLOCK_NULL.
Undefined behavior
If Argobots is not initialized, the results are undefined.
If rwlock is not locked, the results are undefined.
Parameters
[in]rwlockreaders-writer lock handle
Returns
Error code

Definition at line 253 of file rwlock.c.

◆ ABT_rwlock_wrlock()

int ABT_rwlock_wrlock ( ABT_rwlock  rwlock)

Lock a readers-writer lock as a writer.

ABT_rwlock_wrlock() locks the readers-writer lock rwlock as a writer. If this routine successfully returns, the caller acquires rwlock. If rwlock has been locked by either a reader or another writer, the caller is blocked on rwlock until rwlock becomes available.

rwlock may be acquired by only a single writer.

Changes from Argobots 1.x to Argobots 2.0 (planned)
[Argobots 1.x] If a tasklet calls this routine, ABT_ERR_RWLOCK is returned.
[Argobots 2.0] A tasklet may call this routine.
Rationale
Argobots 2.0 integrates a ULT and a tasklet into a single thread concept to make the API more general.
Execution context
[Argobots 1.x] This routine can be called in a ULT context or an external thread context. Argobots must be initialized. This routine may switch the context of the calling ULT if rwlock is locked. Otherwise, this routine does not switch the context of the calling ULT unless any user-defined function that is involved in this routine switch the context of the calling ULT.
[Argobots 2.0] This routine can be called in any execution context. Argobots must be initialized. This routine may switch the context of the calling ULT if rwlock is locked. Otherwise, this routine does not switch the context of the calling ULT unless any user-defined function that is involved in this routine switch the context of the calling ULT.
Errors
ABT_SUCCESS is returned if this routine succeeds.
ABT_ERR_INV_RWLOCK is returned if rwlock is ABT_RWLOCK_NULL.
[Argobots 1.x] ABT_ERR_RWLOCK is returned if the caller is a tasklet.
Undefined behavior
If Argobots is not initialized, the results are undefined.
Parameters
[in]rwlockreaders-writer lock handle
Returns
Error code

Definition at line 199 of file rwlock.c.