Group Lock

Table of Contents

1. Introduction
2. Usage
   1. Creation
   2. Lock and Unlock
   3. Destroy
   4. Registering Member to The Group Lock
   5. Session Management
   6. Synchronization with External Locks
   7. Lock Replace
3. Debugging

Group Lock (pj_grp_lock_t) is a new synchronization object in PJLIB for deadlock avoidance and session management.

Introduction

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)

Usage

Creation

The group lock can be created either by the first member in the group or by the higher object that manages the members. Once created, the ownership of the group lock will be shared by the members, using a reference counter. The group lock will have its own pool. Also a group lock is a pj_lock_t object, hence lock API can be used.

typedef struct pj_grp_lock_config 
{
   unsigned flags;
};

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

Lock and Unlock

The group lock is a lock that can be used as mutex. You can use lock API pj_lock_acquire(), pj_lock_tryacquire(), and pj_lock_release(), or the group lock's own API pj_grp_lock_acquire(), pj_grp_lock_tryacquire(), and pj_grp_lock_release(). Locking the group lock temporarily increases the reference counter to prevent it from being destroyed. The side effect is, the pj_grp_lock_release() may cause the group to be destroyed, if it is the last one that holds the reference counter. In that case, it returns PJ_EGONE.

Destroy

The group lock lifetime is governed by an internal reference counter (see Session Management below). It will be destroyed once the reference counter reaches zero.

Since group lock is a lock object, it can be destroyed with pj_lock_destroy() API. This will forcefully destroy the group lock without adhering to the reference counter, thus should be avoided.

Registering Member to The Group Lock

The purpose of registering a member to the group lock is to prevent that member from being destroyed prematurely, when other threads are referencing the member. To achieve that, the member registers a callback to be called by the group lock to destroy itself when the reference counter of the group reaches zero. In other words, once registered, a member must not allow itself to be destroyed unless the request comes from the group lock's destroy callback.

The API to register a member:

PJ_DECL(pj_status_t) pj_grp_lock_add_handler(pj_grp_lock_t *grp_lock,
                                             pj_pool_t *pool,
                                             void *member,
                                             void (*destroy)(void *member));

Sometimes a member needs to die early (for example, transactions may come and go in a dialog). A member may unregister the handler using this API:

PJ_DECL(pj_status_t) pj_grp_lock_del_handler(pj_grp_lock_t *grp_lock,
                                             void *member,
                                             void (*destroy)(void *member));

Session Management

This API manages the reference counter of the group:

PJ_DECL(pj_status_t) pj_grp_lock_add_ref(pj_grp_lock_t *grp_lock);
PJ_DECL(pj_status_t) pj_grp_lock_dec_ref(pj_grp_lock_t *grp_lock);

The pj_grp_lock_dec_ref() returns PJ_EGONE when that operation causes the group lock to be destroyed (because the reference counter reaches zero).

Synchronization with External Locks

Often it is necessary to synchronize the group lock with an external lock. By external, it means a lock owned by object outside the group, and it’s not possible to to add that object to the group. The PJSUA lock and ioqueue locks are examples of such locks. Synchronizing these locks will guarantee the lock ordering of the locks hence deadlock will be avoided.

Use the API below to synchronize an external lock with the group lock:

PJ_DECL(pj_status_t) pj_grp_lock_chain_lock(pj_grp_lock_t *grp_lock,
                                            pj_lock_t *external_lock,
                                            int pos);

The pos argument specifies the lock order and also the relative position with regard to lock ordering against the group lock. Lock 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).

This is the API to unregister external lock:

PJ_DECL(pj_status_t) pj_grp_lock_unchain_lock(pj_grp_lock_t *grp_lock,
                                              pj_lock_t *external_lock);

Lock Replace

This API is used to move things from the old lock to the new lock and close the old lock. It is especially useful

PJ_DECL(pj_status_t) pj_grp_lock_replace(pj_grp_lock_t *old_lock,
                                         pj_grp_lock_t *new_lock);

Debugging

To enable debugging, declare PJ_GRP_LOCK_DEBUG to non-zero in your config_site.h. With this, now every call to pj_grp_lock_dec_ref() will cause the group lock state to be printed to log at level four. This info includes the current value of the reference counter, along with the source file and line number info of the code that adds the reference counter.

Note though that each pj_grp_lock_acquire() and pj_grp_lock_release() also increments and decrements the reference counter, hence they will also cause info to be dump.

If you after this find out that the leaking reference is caused by timer, you can enable timer heap debugging by setting PJ_TIMER_DEBUG to non-zero and call pj_timer_heap_dump() to dump the state of the timer heap including information about the source file and line number of code that registered currently active timer entries.