Group PJ_GRP_LOCK

group PJ_GRP_LOCK

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.

Defines

pj_grp_lock_add_ref_dbg(grp_lock, x, y)

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(grp_lock, x, y)

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.

Typedefs

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.

Param member:

A pointer to be passed to the handler.

Functions

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_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_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_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_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_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_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_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_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_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_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_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.

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.

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_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_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.

struct pj_grp_lock_config
#include <lock.h>

Settings for creating the group lock.

Public Members

unsigned flags

Creation flags, currently must be zero.