Locks

Files
file	afw_lock.h
	Adaptive Framework locks.

Data Structures
struct	afw_lock_s
struct	afw_lock_rw_s

Macros
#define	AFW_LOCK_BEGIN(instance)
	Macro to begin a lock section. More...
#define	AFW_LOCK_END
	Macro to end a lock section. More...
#define	AFW_LOCK_READ_BEGIN(instance)
	Macro to begin a read lock section for pool. More...
#define	AFW_LOCK_READ_END
	Macro to end a read lock section for pool. More...
#define	AFW_LOCK_WRITE_BEGIN(instance)
	Macro to begin a write lock section. More...
#define	AFW_LOCK_WRITE_END
	Macro to end a write lock section. More...

Enumerations
enum	afw_lock_type_t {   afw_lock_type_global_mutex , afw_lock_type_process_mutex , afw_lock_type_thread_mutex , afw_lock_type_thread_recursive_mutex ,   afw_lock_type_thread_read_write }
	Lock type.

Functions
const afw_lock_t *	afw_lock_create (const afw_utf8_t *lock_id, const afw_utf8_t *brief, const afw_utf8_t *description, afw_boolean_t insure_recursive_lock, const afw_pool_t *p, afw_xctx_t *xctx)
	Create a lock that will last for life of pool. More...
const afw_lock_t *	afw_lock_create_and_register (const afw_utf8_t *lock_id, const afw_utf8_t *brief, const afw_utf8_t *description, afw_boolean_t insure_recursive_lock, afw_xctx_t *xctx)
	Create a lock and register in environment. More...
const afw_lock_t *	afw_lock_create_environment_lock (const afw_utf8_t *lock_id, const afw_pool_t *p, afw_xctx_t *xctx)
void	afw_lock_obtain (const afw_lock_t *instance, afw_xctx_t *xctx)
	Obtain lock. More...
void	afw_lock_obtain_debug (const afw_lock_t *instance, afw_xctx_t *xctx, const afw_utf8_z_t *source_z)
	Debug version of obtain lock. More...
void	afw_lock_release (const afw_lock_t *instance, afw_xctx_t *xctx)
	Release lock. More...
void	afw_lock_release_debug (const afw_lock_t *instance, afw_xctx_t *xctx, const afw_utf8_z_t *source_z)
	Debug version of release lock. More...
const afw_lock_rw_t *	afw_lock_create_rw (const afw_utf8_t *lock_id, const afw_utf8_t *brief, const afw_utf8_t *description, const afw_pool_t *p, afw_xctx_t *xctx)
	Create a read/write lock that will last for life of pool. More...
const afw_lock_rw_t *	afw_lock_create_rw_and_register (const afw_utf8_t *lock_id, const afw_utf8_t *brief, const afw_utf8_t *description, afw_xctx_t *xctx)
	Create a read/write lock and register in environment. More...
void	afw_lock_read_obtain (const afw_lock_rw_t *instance, afw_xctx_t *xctx)
	Obtain read lock. More...
void	afw_lock_read_obtain_debug (const afw_lock_rw_t *instance, afw_xctx_t *xctx, const afw_utf8_z_t *source_z)
	Debug version of obtain read lock. More...
void	afw_lock_read_release (const afw_lock_rw_t *instance, afw_xctx_t *xctx)
	Release read lock. More...
void	afw_lock_read_release_debug (const afw_lock_rw_t *instance, afw_xctx_t *xctx, const afw_utf8_z_t *source_z)
	Debug version of release read lock. More...
void	afw_lock_write_obtain (const afw_lock_rw_t *instance, afw_xctx_t *xctx)
	Obtain write lock. More...
void	afw_lock_write_obtain_debug (const afw_lock_rw_t *instance, afw_xctx_t *xctx, const afw_utf8_z_t *source_z)
	Debug version of obtain write lock. More...
void	afw_lock_write_release (const afw_lock_rw_t *instance, afw_xctx_t *xctx)
	Release write lock. More...
void	afw_lock_write_release_debug (const afw_lock_rw_t *instance, afw_xctx_t *xctx, const afw_utf8_z_t *source_z)
	Debug version of release write lock. More...

Detailed Description

Locks API.

Macro Definition Documentation

AFW_LOCK_BEGIN

#define AFW_LOCK_BEGIN

(

instance

)

Value:

const afw_lock_t *this_LOCK = instance; \
afw_lock_obtain(this_LOCK, xctx); \
AFW_TRY

Macro to begin a lock section.

Parameters

instance

lock.

The variable name of the current xctx must be named xctx.

Usage:

AFW_LOCK_BEGIN(instance) { ... code } AFW_LOCK_END;

Definition at line 191 of file afw_lock.h.

AFW_LOCK_END

#define AFW_LOCK_END

Value:

AFW_FINALLY { \
    afw_lock_release(this_LOCK, xctx); \
} \
AFW_ENDTRY

Macro to end a lock section.

See AFW_LOCK_BEGIN for usage.

Definition at line 202 of file afw_lock.h.

AFW_LOCK_READ_BEGIN

#define AFW_LOCK_READ_BEGIN

(

instance

)

Value:

const afw_lock_rw_t *this_LOCK = instance; \
    afw_lock_read_obtain(this_LOCK, xctx); \
AFW_TRY

Macro to begin a read lock section for pool.

Parameters

instance

of read write lock or NULL to ignore.

The variable name of the current xctx must be named xctx.

Usage:

AFW_LOCK_READ_BEGIN(instance, xctx) { ... code that uses pool } AFW_LOCK_READ_END;

Definition at line 309 of file afw_lock.h.

AFW_LOCK_READ_END

#define AFW_LOCK_READ_END

Value:

AFW_FINALLY { \
    afw_lock_read_release(this_LOCK, xctx); \
} \
AFW_ENDTRY

Macro to end a read lock section for pool.

See AFW_LOCK_READ_BEGIN for usage.

Definition at line 320 of file afw_lock.h.

AFW_LOCK_WRITE_BEGIN

#define AFW_LOCK_WRITE_BEGIN

(

instance

)

Value:

const afw_lock_rw_t *this_LOCK = instance; \
    afw_lock_write_obtain(this_LOCK, xctx); \
AFW_TRY

Macro to begin a write lock section.

Parameters

instance

of read write lock or NULL to ignore.

The variable name of the current xctx must be named xctx.

Usage:

AFW_LOCK_WRITE_BEGIN(instance, xctx) { ... code that uses pool } AFW_LOCK_WRITE_END;

Definition at line 400 of file afw_lock.h.

AFW_LOCK_WRITE_END

#define AFW_LOCK_WRITE_END

Value:

AFW_FINALLY { \
    afw_lock_write_release(this_LOCK, xctx); \
} \
AFW_ENDTRY

Macro to end a write lock section.

See AFW_LOCK_WRITE_BEGIN for usage.

Definition at line 411 of file afw_lock.h.

Function Documentation

afw_lock_create()

const afw_lock_t* afw_lock_create	(	const afw_utf8_t *	lock_id,
		const afw_utf8_t *	brief,
		const afw_utf8_t *	description,
		afw_boolean_t	insure_recursive_lock,
		const afw_pool_t *	p,
		afw_xctx_t *	xctx
	)

Create a lock that will last for life of pool.

Parameters

lock_id
insure_recursive_lock	true insures this is a recursive lock. If false the lock will be recursive only if it's the platform default.
p	for lock.
xctx	of caller.

Definition at line 92 of file afw_lock.c.

afw_lock_create_and_register()

const afw_lock_t* afw_lock_create_and_register	(	const afw_utf8_t *	lock_id,
		const afw_utf8_t *	brief,
		const afw_utf8_t *	description,
		afw_boolean_t	insure_recursive_lock,
		afw_xctx_t *	xctx
	)

Create a lock and register in environment.

Parameters

lock_id	is required
insure_recursive_lock	true insures this is a recursive lock. If false the lock will be recursive only if it's the platform default.
xctx	of caller.

Definition at line 73 of file afw_lock.c.

afw_lock_create_rw()

const afw_lock_rw_t* afw_lock_create_rw	(	const afw_utf8_t *	lock_id,
		const afw_utf8_t *	brief,
		const afw_utf8_t *	description,
		const afw_pool_t *	p,
		afw_xctx_t *	xctx
	)

Create a read/write lock that will last for life of pool.

Parameters

lock_id
p	for lock.
xctx	of caller.

Definition at line 192 of file afw_lock.c.

afw_lock_create_rw_and_register()

const afw_lock_rw_t* afw_lock_create_rw_and_register	(	const afw_utf8_t *	lock_id,
		const afw_utf8_t *	brief,
		const afw_utf8_t *	description,
		afw_xctx_t *	xctx
	)

Create a read/write lock and register in environment.

Parameters

lock_id
xctx	of caller.

Definition at line 175 of file afw_lock.c.

afw_lock_obtain()

void afw_lock_obtain	(	const afw_lock_t *	instance,
		afw_xctx_t *	xctx
	)

Obtain lock.

Parameters

instance	of lock or NULL to ignore.
xctx	of caller.

Call afw_lock_release() to release the lock.

Definition at line 254 of file afw_lock.c.

afw_lock_obtain_debug()

void afw_lock_obtain_debug	(	const afw_lock_t *	instance,
		afw_xctx_t *	xctx,
		const afw_utf8_z_t *	source_z
	)

Debug version of obtain lock.

Parameters

instance	of lock or NULL to ignore.
xctx	of caller.
source_z	file:line where function called.

See also

afw_lock_read()

Definition at line 273 of file afw_lock.c.

afw_lock_read_obtain()

void afw_lock_read_obtain	(	const afw_lock_rw_t *	instance,
		afw_xctx_t *	xctx
	)

Obtain read lock.

Parameters

instance	of read write lock or NULL to ignore.
xctx	of caller.

Call afw_lock_unlock_read() to release the lock.

Definition at line 328 of file afw_lock.c.

afw_lock_read_obtain_debug()

void afw_lock_read_obtain_debug	(	const afw_lock_rw_t *	instance,
		afw_xctx_t *	xctx,
		const afw_utf8_z_t *	source_z
	)

Debug version of obtain read lock.

Parameters

instance	of read write lock or NULL to ignore.
xctx	of caller.
source_z	file:line where function called.

See also

afw_lock_read()

Definition at line 347 of file afw_lock.c.

afw_lock_read_release()

void afw_lock_read_release	(	const afw_lock_rw_t *	instance,
		afw_xctx_t *	xctx
	)

Release read lock.

Parameters

instance	of read write lock.
xctx	of caller.

Definition at line 366 of file afw_lock.c.

afw_lock_read_release_debug()

void afw_lock_read_release_debug	(	const afw_lock_rw_t *	instance,
		afw_xctx_t *	xctx,
		const afw_utf8_z_t *	source_z
	)

Debug version of release read lock.

Parameters

instance	of read write lock or NULL to ignore.
xctx	of caller.
source_z	file:line where function called.

See also

afw_lock_unlock_read()

Definition at line 385 of file afw_lock.c.

afw_lock_release()

void afw_lock_release	(	const afw_lock_t *	instance,
		afw_xctx_t *	xctx
	)

Release lock.

Parameters

instance	of lock or NULL to ignore.
xctx	of caller.

Definition at line 291 of file afw_lock.c.

afw_lock_release_debug()

void afw_lock_release_debug	(	const afw_lock_t *	instance,
		afw_xctx_t *	xctx,
		const afw_utf8_z_t *	source_z
	)

Debug version of release lock.

Parameters

instance	of lock or NULL to ignore.
xctx	of caller.
source_z	file:line where function called.

See also

afw_lock_unlock_read()

Definition at line 310 of file afw_lock.c.

afw_lock_write_obtain()

void afw_lock_write_obtain	(	const afw_lock_rw_t *	instance,
		afw_xctx_t *	xctx
	)

Obtain write lock.

Parameters

instance	of read write lock or NULL to ignore.
xctx	of caller.

Call afw_lock_unlock_write() to release the lock.

Definition at line 403 of file afw_lock.c.

afw_lock_write_obtain_debug()

void afw_lock_write_obtain_debug	(	const afw_lock_rw_t *	instance,
		afw_xctx_t *	xctx,
		const afw_utf8_z_t *	source_z
	)

Debug version of obtain write lock.

Parameters

instance	of read write lock or NULL to ignore.
xctx	of caller.
source_z	file:line where function called.

See also

afw_lock_write()

Definition at line 422 of file afw_lock.c.

afw_lock_write_release()

void afw_lock_write_release	(	const afw_lock_rw_t *	instance,
		afw_xctx_t *	xctx
	)

Release write lock.

Parameters

instance	of read write lock or NULL to ignore.
xctx	of caller.

afw_lock_unlock_write() must be called from the thread that has the pool locked for write.

Definition at line 438 of file afw_lock.c.

afw_lock_write_release_debug()

void afw_lock_write_release_debug	(	const afw_lock_rw_t *	instance,
		afw_xctx_t *	xctx,
		const afw_utf8_z_t *	source_z
	)

Debug version of release write lock.

Parameters

instance	of read write lock or NULL to ignore.
xctx	of caller.
source_z	file:line where function called.

See also

afw_lock_unlock_write()

Definition at line 457 of file afw_lock.c.