Named mutex and read-write locks

Macros
#define	ast_named_lock_get(lock_type, keyspace, key)
	Geta named lock handle. More...
#define	ast_named_lock_put(lock)   ao2_cleanup(lock)
	Put a named lock handle away. More...

Enumerations
enum	ast_named_lock_type { AST_NAMED_LOCK_TYPE_MUTEX = AO2_ALLOC_OPT_LOCK_MUTEX, AST_NAMED_LOCK_TYPE_RWLOCK = AO2_ALLOC_OPT_LOCK_RWLOCK }
	Which type of lock to request. More...

Functions
struct ast_named_lock *	__ast_named_lock_get (const char *filename, int lineno, const char *func, enum ast_named_lock_type lock_type, const char *keyspace, const char *key)

Detailed Description

Named mutex and read-write locks

Since

13.9.0

Locking some objects like sorcery objects can be tricky because the underlying ao2 object may not be the same for all callers. For instance, two threads that call ast_sorcery_retrieve_by_id on the same aor name might actually get 2 different ao2 objects if the underlying wizard had to rehydrate the aor from a database. Locking one ao2 object doesn't have any effect on the other even if those objects had locks in the first placeNamed locks allow access control by name. Now an aor named "1000" can be locked and any other thread attempting to lock the aor named "1000" will wait regardless of whether the underlying ao2 object is the same or not.To use a named lock: Call ast_named_lock_get with the appropriate keyspace and key. Use the standard ao2 lock/unlock functions as needed. Call ao2_cleanup when you're finished with it.

Macro Definition Documentation

ast_named_lock_get

#define ast_named_lock_get	(		lock_type,
			keyspace,
			key
	)

Value:

__ast_named_lock_get(__FILE__, __LINE__, __PRETTY_FUNCTION__, lock_type, \
      keyspace, key)

Geta named lock handle.

Since

13.9.0

Parameters

lock_type	One of ast_named_lock_type
keyspace
key

Return values

A	pointer to an ast_named_lock structure
NULL	on error

Note

keyspace and key can be anything. For sorcery objects, keyspace could be the object type and key could be the object id.

Definition at line 83 of file named_locks.h.

Referenced by aor_alloc(), AST_TEST_DEFINE(), expire_contact(), and lock_thread().

ast_named_lock_put

#define ast_named_lock_put

(

lock

)

ao2_cleanup(lock)

Put a named lock handle away.

Since

13.9.0

Parameters

lock	The pointer to the ast_named_lock structure returned by ast_named_lock_get

Definition at line 93 of file named_locks.h.

Referenced by AST_TEST_DEFINE(), expire_contact(), and lock_thread().

Enumeration Type Documentation

ast_named_lock_type

enum ast_named_lock_type

Which type of lock to request.

Enumerator
AST_NAMED_LOCK_TYPE_MUTEX	Request a named mutex.
AST_NAMED_LOCK_TYPE_RWLOCK	Request a named read/write lock.

Definition at line 57 of file named_locks.h.

                         {
   /*! Request a named mutex. */
   AST_NAMED_LOCK_TYPE_MUTEX = AO2_ALLOC_OPT_LOCK_MUTEX,
   /*! Request a named read/write lock. */
   AST_NAMED_LOCK_TYPE_RWLOCK = AO2_ALLOC_OPT_LOCK_RWLOCK,
};

Function Documentation

__ast_named_lock_get()

struct ast_named_lock* __ast_named_lock_get	(	const char *	filename,
		int	lineno,
		const char *	func,
		enum ast_named_lock_type	lock_type,
		const char *	keyspace,
		const char *	key
	)

Definition at line 70 of file named_locks.c.

References __ao2_alloc(), __ao2_weakproxy_find(), AO2_ALLOC_OPT_LOCK_MASK, ao2_cleanup, ao2_link_flags, ao2_lock, ao2_options_get(), ao2_t_ref, ao2_t_weakproxy_alloc, ao2_unlock, ao2_weakproxy_set_object, ao2_weakproxy_subscribe(), ast_alloca, ast_assert, named_lock_proxy::key, lock, named_lock_proxy_cb(), NULL, OBJ_NOLOCK, and OBJ_SEARCH_KEY.

{
   struct named_lock_proxy *proxy;
   struct ast_named_lock *lock;
   int keylen = strlen(keyspace) + strlen(key) + 2;
   char *concat_key = ast_alloca(keylen);

   sprintf(concat_key, "%s-%s", keyspace, key); /* Safe */

   ao2_lock(named_locks);
   lock = __ao2_weakproxy_find(named_locks, concat_key, OBJ_SEARCH_KEY | OBJ_NOLOCK,
      __PRETTY_FUNCTION__, filename, lineno, func);
   if (lock) {
      ast_assert((ao2_options_get(lock) & AO2_ALLOC_OPT_LOCK_MASK) == lock_type);
      ao2_unlock(named_locks);

      return lock;
   }

   proxy = ao2_t_weakproxy_alloc(sizeof(*proxy) + keylen, NULL, concat_key);
   if (!proxy) {
      goto failure_cleanup;
   }

   lock = __ao2_alloc(sizeof(*lock) + keylen, NULL, lock_type, concat_key, filename, lineno, func);
   if (!lock) {
      goto failure_cleanup;
   }

   /* We have exclusive access to proxy and lock, no need for locking here. */
   if (ao2_weakproxy_set_object(proxy, lock, OBJ_NOLOCK)) {
      goto failure_cleanup;
   }

   if (ao2_weakproxy_subscribe(proxy, named_lock_proxy_cb, NULL, OBJ_NOLOCK)) {
      goto failure_cleanup;
   }

   strcpy(proxy->key, concat_key); /* Safe */
   ao2_link_flags(named_locks, proxy, OBJ_NOLOCK);
   ao2_unlock(named_locks);
   ao2_t_ref(proxy, -1, "Release allocation reference");

   return lock;

failure_cleanup:
   ao2_unlock(named_locks);

   ao2_cleanup(proxy);
   ao2_cleanup(lock);

   return NULL;
}