Group Lock

Data Structures
struct	pj_grp_lock_config

Macros
#define	pj_grp_lock_add_ref_dbg(grp_lock, x, y)   pj_grp_lock_add_ref(grp_lock)
#define	pj_grp_lock_dec_ref_dbg(grp_lock, x, y)   pj_grp_lock_dec_ref(grp_lock)

Typedefs
typedef void(*	pj_grp_lock_handler) (void *member)

Functions
void	pj_grp_lock_config_default (pj_grp_lock_config *cfg)
pj_status_t	pj_grp_lock_create (pj_pool_t *pool, const pj_grp_lock_config *cfg, pj_grp_lock_t **p_grp_lock)
pj_status_t	pj_grp_lock_create_w_handler (pj_pool_t *pool, const pj_grp_lock_config *cfg, void *member, pj_grp_lock_handler handler, pj_grp_lock_t **p_grp_lock)
pj_status_t	pj_grp_lock_destroy (pj_grp_lock_t *grp_lock)
pj_status_t	pj_grp_lock_replace (pj_grp_lock_t *old_lock, pj_grp_lock_t *new_lock)
pj_status_t	pj_grp_lock_acquire (pj_grp_lock_t *grp_lock)
pj_status_t	pj_grp_lock_tryacquire (pj_grp_lock_t *grp_lock)
pj_status_t	pj_grp_lock_release (pj_grp_lock_t *grp_lock)
pj_status_t	pj_grp_lock_add_handler (pj_grp_lock_t *grp_lock, pj_pool_t *pool, void *member, pj_grp_lock_handler handler)
pj_status_t	pj_grp_lock_del_handler (pj_grp_lock_t *grp_lock, void *member, pj_grp_lock_handler handler)
pj_status_t	pj_grp_lock_add_ref (pj_grp_lock_t *grp_lock)
pj_status_t	pj_grp_lock_dec_ref (pj_grp_lock_t *grp_lock)
int	pj_grp_lock_get_ref (pj_grp_lock_t *grp_lock)
void	pj_grp_lock_dump (pj_grp_lock_t *grp_lock)
pj_status_t	pj_grp_lock_chain_lock (pj_grp_lock_t *grp_lock, pj_lock_t *ext_lock, int pos)
pj_status_t	pj_grp_lock_unchain_lock (pj_grp_lock_t *grp_lock, pj_lock_t *ext_lock)

Detailed Description

Group lock is a synchronization object to manage concurrency among members within the same logical group. Example of such groups are:

• dialog, which has members such as the dialog itself, an invite session, and several transactions
• ICE, which has members such as ICE stream transport, ICE session, STUN socket, TURN socket, and down to ioqueue key

Group lock has three functions:

• mutual exclusion: to protect resources from being accessed by more than one threads at the same time
• session management: to make sure that the resource is not destroyed while others are still using or about to use it.
• lock coordinator: to provide uniform lock ordering among more than one lock objects, which is necessary to avoid deadlock.

The requirements of the group lock are:

• must satisfy all the functions above
• must allow members to join or leave the group (for example, transaction may be added or removed from a dialog)
• must be able to synchronize with external lock (for example, a dialog lock must be able to sync itself with PJSUA lock)

Please see https://trac.pjsip.org/repos/wiki/Group_Lock for more info.

Macro Definition Documentation

pj_grp_lock_add_ref_dbg

#define pj_grp_lock_add_ref_dbg	(		grp_lock,
			x,
			y
	)		pj_grp_lock_add_ref(grp_lock)

Debug version of pj_grp_lock_add_ref(), allowing to specify file and lineno.

Parameters

grp_lock	The group lock.
x	Filename
y	Line number

Returns

PJ_SUCCESS or the appropriate error code.

pj_grp_lock_dec_ref_dbg

#define pj_grp_lock_dec_ref_dbg	(		grp_lock,
			x,
			y
	)		pj_grp_lock_dec_ref(grp_lock)

Debug version of pj_grp_lock_dec_ref(), allowing to specify file and lineno.

Parameters

grp_lock	The group lock.
x	Filename
y	Line number

Returns

PJ_SUCCESS or the appropriate error code.

Typedef Documentation

pj_grp_lock_handler

typedef void(* pj_grp_lock_handler) (void *member)

The group lock destroy handler, a destructor function called when a group lock is about to be destroyed.

Parameters

member

A pointer to be passed to the handler.

Function Documentation

pj_grp_lock_acquire()

pj_status_t pj_grp_lock_acquire

(

pj_grp_lock_t *

grp_lock

)

Acquire lock on the specified group lock.

Parameters

grp_lock

The group lock.

Returns

PJ_SUCCESS or the appropriate error code.

pj_grp_lock_add_handler()

pj_status_t pj_grp_lock_add_handler	(	pj_grp_lock_t *	grp_lock,
		pj_pool_t *	pool,
		void *	member,
		pj_grp_lock_handler	handler
	)

Add a destructor handler, to be called by the group lock when it is about to be destroyed.

Parameters

grp_lock	The group lock.
pool	Pool to allocate memory for the handler.
member	A pointer to be passed to the handler.
handler	The destroy handler.

Returns

PJ_SUCCESS or the appropriate error code.

pj_grp_lock_add_ref()

pj_status_t pj_grp_lock_add_ref

(

pj_grp_lock_t *

grp_lock

)

Increment reference counter to prevent the group lock grom being destroyed.

Parameters

grp_lock

The group lock.

Returns

PJ_SUCCESS or the appropriate error code.

pj_grp_lock_chain_lock()

pj_status_t pj_grp_lock_chain_lock	(	pj_grp_lock_t *	grp_lock,
		pj_lock_t *	ext_lock,
		int	pos
	)

Synchronize an external lock with the group lock, by adding it to the list of locks to be acquired by the group lock when the group lock is acquired.

The ''pos'' argument specifies the lock order and also the relative position with regard to lock ordering against the group lock. Locks with lower ''pos'' value will be locked first, and those with negative value will be locked before the group lock (the group lock's ''pos'' value is zero).

Parameters

grp_lock	The group lock.
ext_lock	The external lock
pos	The position.

Returns

PJ_SUCCESS or the appropriate error code.

pj_grp_lock_config_default()

void pj_grp_lock_config_default

(

pj_grp_lock_config *

cfg

)

Initialize the config with the default values.

Parameters

cfg	The config to be initialized.

pj_grp_lock_create()

pj_status_t pj_grp_lock_create	(	pj_pool_t *	pool,
		const pj_grp_lock_config *	cfg,
		pj_grp_lock_t **	p_grp_lock
	)

Create a group lock object. Initially the group lock will have reference counter of zero.

Parameters

pool	The group lock only uses the pool parameter to get the pool factory, from which it will create its own pool.
cfg	Optional configuration.
p_grp_lock	Pointer to receive the newly created group lock.

Returns

PJ_SUCCESS or the appropriate error code.

pj_grp_lock_create_w_handler()

pj_status_t pj_grp_lock_create_w_handler	(	pj_pool_t *	pool,
		const pj_grp_lock_config *	cfg,
		void *	member,
		pj_grp_lock_handler	handler,
		pj_grp_lock_t **	p_grp_lock
	)

Create a group lock object, with the specified destructor handler, to be called by the group lock when it is about to be destroyed. Initially the group lock will have reference counter of zero.

Parameters

pool	The group lock only uses the pool parameter to get the pool factory, from which it will create its own pool.
cfg	Optional configuration.
member	A pointer to be passed to the handler.
handler	The destroy handler.
p_grp_lock	Pointer to receive the newly created group lock.

Returns

PJ_SUCCESS or the appropriate error code.

pj_grp_lock_dec_ref()

pj_status_t pj_grp_lock_dec_ref

(

pj_grp_lock_t *

grp_lock

)

Decrement the reference counter. When the counter value reaches zero, the group lock will be destroyed and all destructor handlers will be called.

Parameters

grp_lock

The group lock.

Returns

PJ_SUCCESS or the appropriate error code.

pj_grp_lock_del_handler()

pj_status_t pj_grp_lock_del_handler	(	pj_grp_lock_t *	grp_lock,
		void *	member,
		pj_grp_lock_handler	handler
	)

Remove previously registered handler. All parameters must be the same as when the handler was added.

Parameters

grp_lock	The group lock.
member	A pointer to be passed to the handler.
handler	The destroy handler.

Returns

PJ_SUCCESS or the appropriate error code.

pj_grp_lock_destroy()

pj_status_t pj_grp_lock_destroy

(

pj_grp_lock_t *

grp_lock

)

Forcibly destroy the group lock, ignoring the reference counter value.

Parameters

grp_lock

The group lock.

Returns

PJ_SUCCESS or the appropriate error code.

pj_grp_lock_dump()

void pj_grp_lock_dump

(

pj_grp_lock_t *

grp_lock

)

Dump group lock info for debugging purpose. If group lock debugging is enabled (via PJ_GRP_LOCK_DEBUG) macro, this will print the group lock reference counter value along with the source file and line. If debugging is disabled, this will only print the reference counter.

Parameters

grp_lock

The group lock.

pj_grp_lock_get_ref()

int pj_grp_lock_get_ref

(

pj_grp_lock_t *

grp_lock

)

Get current reference count value. This normally is only used for debugging purpose.

Parameters

grp_lock

The group lock.

Returns

The reference count value.

pj_grp_lock_release()

pj_status_t pj_grp_lock_release

(

pj_grp_lock_t *

grp_lock

)

Release the previously held lock. This may cause the group lock to be destroyed if it is the last one to hold the reference counter. In that case, the function will return PJ_EGONE.

Parameters

grp_lock

The group lock.

Returns

PJ_SUCCESS or the appropriate error code.

pj_grp_lock_replace()

pj_status_t pj_grp_lock_replace	(	pj_grp_lock_t *	old_lock,
		pj_grp_lock_t *	new_lock
	)

Move the contents of the old lock to the new lock and destroy the old lock.

Parameters

old_lock	The old group lock to be destroyed.
new_lock	The new group lock.

Returns

PJ_SUCCESS or the appropriate error code.

pj_grp_lock_tryacquire()

pj_status_t pj_grp_lock_tryacquire

(

pj_grp_lock_t *

grp_lock

)

Acquire lock on the specified group lock if it is available, otherwise return immediately wihout waiting.

Parameters

grp_lock

The group lock.

Returns

PJ_SUCCESS or the appropriate error code.

pj_grp_lock_unchain_lock()

pj_status_t pj_grp_lock_unchain_lock	(	pj_grp_lock_t *	grp_lock,
		pj_lock_t *	ext_lock
	)

Remove an external lock from group lock's list of synchronized locks.

Parameters

grp_lock	The group lock.
ext_lock	The external lock

Returns

PJ_SUCCESS or the appropriate error code.