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 1008 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]

newrwlock

readers-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]

rwlock

readers-writer lock handle

Returns

Error code

Definition at line 90 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]

rwlock

readers-writer lock handle

Returns

Error code

Definition at line 144 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]

rwlock

readers-writer lock handle

Returns

Error code

Definition at line 263 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]

rwlock

readers-writer lock handle

Returns

Error code

Definition at line 207 of file rwlock.c.