Changes between Initial Version and Version 1 of Group_Lock

Timestamp:

Feb 13, 2013 7:22:38 AM (12 years ago)

Author:

bennylp

Comment:

--

Group_Lock

@@ +1 @@
+{{{
+#!html
+<!-- MAIN TABLE START -->
+<table border=0 width="90%" align="center"><tr><td>
+}}}
+
+= Group Lock =
+
+'''Table of Contents'''
+[[PageOutline(2-3,,inline)]]
+
+Group Lock ({{{pj_grp_lock_t}}}) is a new synchronization object in PJLIB for deadlock avoidance and session management.
+
+[[BR]]
+
+== 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 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 === #session
+
+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);
+}}}
+
+
+{{{
+#!html
+<!-- MAIN TABLE END -->
+</td></tr></table>
+}}}
+