lock: Add named lock capability

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

Named locks allow access control by keyspace and key strings.  Now an "aor"
named "1000" can be locked and any other thread attempting to lock "aor" "1000"
will wait regardless of whether the underlying ao2 object is the same or not.
Mutex and rwlocks are supported.

This capability will initially be used to lock an aor when multiple threads may
be attempting to prune expired contacts from it.

Change-Id: If258c0b7f92b02d07243ce70e535821a1ea7fb45

2 files changed, 106 insertions, 0 deletions

diff --git a/include/asterisk/_private.h b/include/asterisk/_private.h
index 2148a2082..ebee96cc4 100644
--- a/include/asterisk/_private.h
+++ b/include/asterisk/_private.h
@@ -38,6 +38,7 @@ int dnsmgr_reload(void);		/*!< Provided by dnsmgr.c */
 void threadstorage_init(void);		/*!< Provided by threadstorage.c */
 int ast_device_state_engine_init(void);	/*!< Provided by devicestate.c */
 int astobj2_init(void);			/*!< Provided by astobj2.c */
+int ast_named_locks_init(void);		/*!< Provided by named_locks.c */
 int ast_file_init(void);		/*!< Provided by file.c */
 int ast_features_init(void);            /*!< Provided by features.c */
 void ast_autoservice_init(void);	/*!< Provided by autoservice.c */
diff --git a/include/asterisk/named_locks.h b/include/asterisk/named_locks.h
new file mode 100644
index 000000000..0fe07d992
--- /dev/null
+++ b/include/asterisk/named_locks.h
@@ -0,0 +1,105 @@
+/*
+ * Asterisk -- An open source telephony toolkit.
+ *
+ * Copyright (C) 2016, Fairview 5 Engineering, LLC
+ *
+ * George Joseph <george.joseph@fairview5.com>
+ *
+ * See http://www.asterisk.org for more information about
+ * the Asterisk project. Please do not directly contact
+ * any of the maintainers of this project for assistance;
+ * the project provides a web site, mailing lists and IRC
+ * channels for your use.
+ *
+ * This program is free software, distributed under the terms of
+ * the GNU General Public License Version 2. See the LICENSE file
+ * at the top of the source tree.
+ */
+
+/*! \file
+ *
+ * \brief Named Locks
+ *
+ * \author George Joseph <george.joseph@fairview5.com>
+ */
+
+#ifndef INCLUDE_ASTERISK_NAMED_LOCKS_H_
+#define INCLUDE_ASTERISK_NAMED_LOCKS_H_
+
+#include "asterisk/astobj2.h"
+
+/*!
+ * \defgroup named_locks Named mutex and read-write locks
+ * @{
+ * \page NamedLocks 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 place
+ *
+ * Named 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 ast_named_lock_put when you're finished with it.
+ */
+
+/*!
+ * \brief Which type of lock to request.
+ */
+enum ast_named_lock_type {
+	/*! 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,
+};
+
+struct ast_named_lock;
+
+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);
+
+int __ast_named_lock_put(const char *filename, int lineno, const char *func,
+	struct ast_named_lock *lock);
+
+/*!
+ * \brief Geta named lock handle
+ * \since 13.9.0
+ *
+ * \param lock_type One of ast_named_lock_type
+ * \param keyspace
+ * \param key
+ * \retval A pointer to an ast_named_lock structure
+ * \retval 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.
+ */
+#define ast_named_lock_get(lock_type, keyspace, key) \
+	__ast_named_lock_get(__FILE__, __LINE__, __PRETTY_FUNCTION__, lock_type, \
+		keyspace, key)
+
+/*!
+ * \brief Put a named lock handle away
+ * \since 13.9.0
+ *
+ * \param lock The pointer to the ast_named_lock structure returned by ast_named_lock_get
+ * \retval 0 Success
+ * \retval -1 Failure
+ */
+#define ast_named_lock_put(lock) \
+	__ast_named_lock_put(__FILE__, __LINE__, __PRETTY_FUNCTION__, lock)
+
+/*!
+ * @}
+ */
+
+#endif /* INCLUDE_ASTERISK_NAMED_LOCKS_H_ */