[asterisk-commits] oej: branch oej/pine-instance-uuid-1.8 r386610 - in /team/oej/pine-instance-u...
SVN commits to the Asterisk project
asterisk-commits at lists.digium.com
Fri Apr 26 05:59:57 CDT 2013
Author: oej
Date: Fri Apr 26 05:59:53 2013
New Revision: 386610
URL: http://svnview.digium.com/svn/asterisk?view=rev&rev=386610
Log:
A backport of the UUID support from trunk
Added:
team/oej/pine-instance-uuid-1.8/include/asterisk/uuid.h (with props)
team/oej/pine-instance-uuid-1.8/main/uuid.c (with props)
Modified:
team/oej/pine-instance-uuid-1.8/configure
team/oej/pine-instance-uuid-1.8/configure.ac
Modified: team/oej/pine-instance-uuid-1.8/configure.ac
URL: http://svnview.digium.com/svn/asterisk/team/oej/pine-instance-uuid-1.8/configure.ac?view=diff&rev=386610&r1=386609&r2=386610
==============================================================================
--- team/oej/pine-instance-uuid-1.8/configure.ac (original)
+++ team/oej/pine-instance-uuid-1.8/configure.ac Fri Apr 26 05:59:53 2013
@@ -466,11 +466,12 @@
AC_HEADER_SYS_WAIT
AC_CHECK_HEADERS([arpa/inet.h fcntl.h inttypes.h libintl.h limits.h locale.h malloc.h netdb.h netinet/in.h stddef.h stdint.h stdlib.h string.h strings.h sys/event.h sys/file.h sys/ioctl.h sys/param.h sys/socket.h sys/time.h syslog.h termios.h unistd.h utime.h arpa/nameser.h sys/io.h])
-# Any one of these 4 packages support a mandatory requirement, so we want to check on them as early as possible.
+# Any one of these 5 packages support a mandatory requirement, so we want to check on them as early as possible.
AST_EXT_LIB_CHECK([TERMCAP], [termcap], [tgetent], [])
AST_EXT_LIB_CHECK([TINFO], [tinfo], [tgetent], [])
AST_EXT_LIB_CHECK([CURSES], [curses], [initscr], [curses.h])
AST_EXT_LIB_CHECK([NCURSES], [ncurses], [initscr], [curses.h])
+AST_EXT_LIB_CHECK([UUID], [uuid], [uuid_generate_random], [uuid/uuid.h], [-luuid])
EDITLINE_LIB=""
if test "x$TERMCAP_LIB" != "x" ; then
@@ -485,6 +486,10 @@
AC_MSG_ERROR([*** termcap support not found (on modern systems, this typically means the ncurses development package is missing)])
fi
AC_SUBST(EDITLINE_LIB)
+
+if test "x$UUID_LIB" == "x"; then
+ AC_MSG_ERROR([*** uuid support not found (this typically means the uuid development package is missing)])
+fi
# Another mandatory item (unless it's explicitly disabled)
AC_ARG_ENABLE([xmldoc],
Added: team/oej/pine-instance-uuid-1.8/include/asterisk/uuid.h
URL: http://svnview.digium.com/svn/asterisk/team/oej/pine-instance-uuid-1.8/include/asterisk/uuid.h?view=auto&rev=386610
==============================================================================
--- team/oej/pine-instance-uuid-1.8/include/asterisk/uuid.h (added)
+++ team/oej/pine-instance-uuid-1.8/include/asterisk/uuid.h Fri Apr 26 05:59:53 2013
@@ -1,0 +1,118 @@
+/*
+ * Asterisk -- An open source telephony toolkit.
+ *
+ * Copyright (C) 2012, Digium, Inc.
+ *
+ * Mark Michelson <mmmichelson at digium.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 Universally unique identifier support
+ */
+
+#ifndef _ASTERISK_UUID_H
+#define _ASTERISK_UUID_H
+
+/* Size of an RFC 4122 UUID string plus terminating null byte */
+#define AST_UUID_STR_LEN (36 + 1)
+
+struct ast_uuid;
+
+/*!
+ * \brief Initialize the UUID system
+ */
+void ast_uuid_init(void);
+
+/*!
+ * \brief Generate a UUID
+ *
+ * This function allocates memory on the heap. The returned
+ * pointer must be freed using ast_free()
+ *
+ * \retval NULL Generation failed
+ * \retval non-NULL heap-allocated UUID
+ */
+struct ast_uuid *ast_uuid_generate(void);
+
+/*!
+ * \brief Convert a UUID to a string
+ *
+ * \param uuid The UUID to convert to a string
+ * \param[out] buf The buffer where the UUID string will be stored
+ * \param size The size of the buffer. Must be at least AST_UUID_STR_LEN.
+ * \return The UUID string (a pointer to buf)
+ */
+char *ast_uuid_to_str(const struct ast_uuid *uuid, char *buf, size_t size);
+
+/*!
+ * \brief Generate a UUID string.
+ * \since 12.0.0
+ *
+ * \param buf The buffer where the UUID string will be stored
+ * \param size The size of the buffer. Must be at least AST_UUID_STR_LEN.
+ *
+ * \return The UUID string (a pointer to buf)
+ */
+char *ast_uuid_generate_str(char *buf, size_t size);
+
+/*!
+ * \brief Convert a string to a UUID
+ *
+ * This function allocates memory on the heap. The returned
+ * pointer must be freed using ast_free()
+ *
+ * \param str The string to convert to a UUID
+ * \retval NULL Failed to convert
+ * \retval non-NULL The heap-allocated converted UUID
+ */
+struct ast_uuid *ast_str_to_uuid(const char *str);
+
+/*!
+ * \brief Make a copy of a UUID
+ *
+ * This function allocates memory on the heap. The returned
+ * pointer must be freed using ast_free()
+ *
+ * \param src The source UUID to copy
+ * \retval NULL Failed to copy
+ * \retval non-NULL The heap-allocated duplicate UUID
+ */
+struct ast_uuid *ast_uuid_copy(const struct ast_uuid *src);
+
+/*!
+ * \brief Compare two UUIDs
+ *
+ * \param left First UUID to compare
+ * \param right Second UUID to compare
+ * \retval <0 left is lexicographically less than right
+ * \retval 0 left and right are the same
+ * \retval >0 left is lexicographically greater than right
+ */
+int ast_uuid_compare(const struct ast_uuid *left, const struct ast_uuid *right);
+
+/*!
+ * \brief Clear a UUID by setting it to be a nil UUID (all 0s)
+ *
+ * \param uuid UUID to clear
+ */
+void ast_uuid_clear(struct ast_uuid *uuid);
+
+/*!
+ * \brief Check if a UUID is a nil UUID (all 0s)
+ *
+ * \param uuid UUID to check
+ * \retval 0 The UUID is not nil
+ * \retval non-zero The UUID is nil
+ */
+int ast_uuid_is_nil(const struct ast_uuid *uuid);
+#endif
Propchange: team/oej/pine-instance-uuid-1.8/include/asterisk/uuid.h
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: team/oej/pine-instance-uuid-1.8/include/asterisk/uuid.h
------------------------------------------------------------------------------
svn:keywords = Author Date Id Revision
Propchange: team/oej/pine-instance-uuid-1.8/include/asterisk/uuid.h
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added: team/oej/pine-instance-uuid-1.8/main/uuid.c
URL: http://svnview.digium.com/svn/asterisk/team/oej/pine-instance-uuid-1.8/main/uuid.c?view=auto&rev=386610
==============================================================================
--- team/oej/pine-instance-uuid-1.8/main/uuid.c (added)
+++ team/oej/pine-instance-uuid-1.8/main/uuid.c Fri Apr 26 05:59:53 2013
@@ -1,0 +1,229 @@
+/*
+ * Asterisk -- An open source telephony toolkit.
+ *
+ * Copyright (C) 2012, Digium, Inc.
+ *
+ * Mark Michelson <mmmichelson at digium.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 Universally unique identifier support
+ */
+
+#include "asterisk.h"
+#include <uuid/uuid.h>
+#include <fcntl.h>
+
+#include "asterisk/uuid.h"
+#include "asterisk/utils.h"
+#include "asterisk/strings.h"
+#include "asterisk/logger.h"
+#include "asterisk/lock.h"
+
+AST_MUTEX_DEFINE_STATIC(uuid_lock);
+
+static int has_dev_urandom;
+
+struct ast_uuid {
+ uuid_t uu;
+};
+
+/*!
+ * \internal
+ * \brief Generate a UUID.
+ * \since 12.0.0
+ *
+ * \param uuid Fill this with a generated UUID.
+ *
+ * \return Nothing
+ */
+static void generate_uuid(struct ast_uuid *uuid)
+{
+ /* libuuid provides three methods of generating uuids,
+ * uuid_generate(), uuid_generate_random(), and uuid_generate_time().
+ *
+ * uuid_generate_random() creates a UUID based on random numbers. The method
+ * attempts to use either /dev/urandom or /dev/random to generate random values.
+ * If these resources are unavailable, then random numbers will be generated
+ * using C library calls to generate pseudorandom numbers.
+ * This method of generating UUIDs corresponds to section 4.4 of RFC 4122.
+ *
+ * uuid_generate_time() creates a UUID based on the current time plus
+ * a system identifier (MAC address of the ethernet interface). This
+ * method of generating UUIDs corresponds to section 4.2 of RFC 4122.
+ *
+ * uuid_generate() will check if /dev/urandom or /dev/random is available to
+ * use. If so, it will use uuid_generate_random(). Otherwise, it will use
+ * uuid_generate_time(). The idea is that it avoids using pseudorandom
+ * numbers if necessary.
+ *
+ * For our purposes, we do not use the time-based UUID at all. There are
+ * several reasons for this:
+ *
+ * 1) The time-based algorithm makes use of a daemon process (uuidd) in order
+ * to ensure that any concurrent requests for UUIDs result in unique results.
+ * Use of this daemon is a bit dodgy for a few reasons
+ *
+ * a) libuuid assumes a hardcoded location for the .pid file of the daemon.
+ * However, the daemon could already be running on the system in a different
+ * location than expected. If this is the case, then attempting to connect
+ * to the daemon will fail, and attempting to launch another instance in
+ * the expected location will also fail.
+ *
+ * b) If the daemon is not running, then the first attempt to create a
+ * time-based UUID will result in launching the daemon. Because of the hard-
+ * coded locations that libuuid assumes for the daemon, Asterisk must be
+ * run with permissions that will allow for the daemon to be launched in
+ * the expected directories.
+ *
+ * c) Once the daemon is running, concurrent requests for UUIDs are thread-safe.
+ * However, the actual launching of the daemon is not thread-safe since libuuid
+ * uses no synchronization primitives to ensure that only one thread (or process)
+ * launches the daemon.
+ *
+ * d) When libuuid launches the daemon, it sets an inactivity timer.
+ * If no UUID generation requests are issued in that time period,
+ * then the daemon will exit. If a new request should occur after the daemon
+ * exits, then the daemon will be relaunched. Given point c), we cannot
+ * necessarily guarantee the thread-safety of time-based UUID generation since
+ * we cannot necessarily guarantee the daemon is running as we expect.
+ * We could set up a watchdog thread to generate UUIDs at regular intervals to
+ * prevent the daemon from exiting, but frankly, that sucks.
+ *
+ * 2) Since the MAC address of the Ethernet interface is part of the UUID when
+ * using the time-based method, there is information leaked.
+ *
+ * Given these drawbacks, we stick to only using random UUIDs. The chance of /dev/random
+ * or /dev/urandom not existing on systems in this age is next to none.
+ */
+
+ /* XXX Currently, we only protect this call if the user has no /dev/urandon on their system.
+ * If it turns out that there are issues with UUID generation despite the presence of
+ * /dev/urandom, then we may need to make the locking/unlocking unconditional.
+ */
+ if (!has_dev_urandom) {
+ ast_mutex_lock(&uuid_lock);
+ }
+ uuid_generate_random(uuid->uu);
+ if (!has_dev_urandom) {
+ ast_mutex_unlock(&uuid_lock);
+ }
+}
+
+struct ast_uuid *ast_uuid_generate(void)
+{
+ struct ast_uuid *uuid = ast_malloc(sizeof(*uuid));
+
+ if (!uuid) {
+ return NULL;
+ }
+ generate_uuid(uuid);
+ return uuid;
+}
+
+char *ast_uuid_to_str(const struct ast_uuid *uuid, char *buf, size_t size)
+{
+ ast_assert(size >= AST_UUID_STR_LEN);
+ uuid_unparse_lower(uuid->uu, buf);
+ return buf;
+}
+
+char *ast_uuid_generate_str(char *buf, size_t size)
+{
+ struct ast_uuid uuid;
+
+ generate_uuid(&uuid);
+ return ast_uuid_to_str(&uuid, buf, size);
+}
+
+struct ast_uuid *ast_str_to_uuid(const char *str)
+{
+ struct ast_uuid *uuid = ast_malloc(sizeof(*uuid));
+ int res;
+
+ if (!uuid) {
+ return NULL;
+ }
+ res = uuid_parse(str, uuid->uu);
+ if (res) {
+ ast_log(LOG_WARNING, "Unable to convert string %s into a UUID\n", str);
+ ast_free(uuid);
+ return NULL;
+ }
+ return uuid;
+}
+
+struct ast_uuid *ast_uuid_copy(const struct ast_uuid *src)
+{
+ struct ast_uuid *dst = ast_malloc(sizeof(*dst));
+
+ if (!dst) {
+ return NULL;
+ }
+ uuid_copy(dst->uu, src->uu);
+ return dst;
+}
+
+int ast_uuid_compare(const struct ast_uuid *left, const struct ast_uuid *right)
+{
+ return uuid_compare(left->uu, right->uu);
+}
+
+void ast_uuid_clear(struct ast_uuid *uuid)
+{
+ uuid_clear(uuid->uu);
+}
+
+int ast_uuid_is_nil(const struct ast_uuid *uuid)
+{
+ return uuid_is_null(uuid->uu);
+}
+
+void ast_uuid_init(void)
+{
+ /* This requires some explanation.
+ *
+ * libuuid generates UUIDs based on random number generation. This involves
+ * opening a handle to /dev/urandom or /dev/random in order to get random
+ * data for the UUIDs.
+ *
+ * This is thread-safe, to a point. The problem is that the first attempt
+ * to generate a UUID will result in opening the random number handle. Once
+ * the handle is opened, all further generation is thread safe. This
+ * first generation can be potentially risky if multiple threads attempt
+ * to generate a UUID at the same time, though, since there is no thread
+ * synchronization used within libuuid. To get around this potential
+ * issue, we go ahead and generate a UUID up front so that the underlying
+ * work is done before we start requesting UUIDs for real.
+ *
+ * Think of this along the same lines as initializing a singleton.
+ */
+ uuid_t uu;
+ int dev_urandom_fd;
+
+ dev_urandom_fd = open("/dev/urandom", O_RDONLY);
+ if (dev_urandom_fd < 0) {
+ ast_log(LOG_WARNING, "It appears your system does not have /dev/urandom on it. This\n"
+ "means that UUID generation will use a pseudorandom number generator. Since\n"
+ "the thread-safety of your system's random number generator cannot\n"
+ "be guaranteed, we have to synchronize UUID generation. This may result\n"
+ "in decreased performance. It is highly recommended that you set up your\n"
+ "system to have /dev/urandom\n");
+ } else {
+ has_dev_urandom = 1;
+ close(dev_urandom_fd);
+ }
+ uuid_generate_random(uu);
+
+ ast_debug(1, "UUID system initiated\n");
+}
Propchange: team/oej/pine-instance-uuid-1.8/main/uuid.c
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: team/oej/pine-instance-uuid-1.8/main/uuid.c
------------------------------------------------------------------------------
svn:keywords = Author Date Id Revision
Propchange: team/oej/pine-instance-uuid-1.8/main/uuid.c
------------------------------------------------------------------------------
svn:mime-type = text/plain
More information about the asterisk-commits
mailing list