Redesigned 'optional API' support.

This patch provides a new implementation of the optional API support defined
in asterisk/optional_api.h; this new version provides solves compatibility
issues with the use of linker version scripts for suppressing global symbols.
In addition, there is now a functional (and tested!) implementation for Mac OS/X,
so module writers no longer need to use special tests before calling optional
API functions. All future implementations must provide these same semantics,
so that module writers can rely on them.



git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@200519 65c4cc65-6c06-0410-ace0-fbb531ad65f3

1 files changed, 131 insertions, 17 deletions

diff --git a/include/asterisk/optional_api.h b/include/asterisk/optional_api.h
index 1af596ec1..df875a849 100644
--- a/include/asterisk/optional_api.h
+++ b/include/asterisk/optional_api.h
@@ -32,14 +32,14 @@
  *
  * To accomodate this situation, the AST_OPTIONAL_API macro allows an API
  * function to be declared in a special way, if Asterisk being built on a
- * platform that supports the GCC 'weak' and 'alias' attributes. If so,
- * the API function is actually a weak symbol, which means if the provider
- * of the API is not loaded, the symbol can still be referenced (unlike a
+ * platform that supports special compiler and dynamic linker attributes.
+ * If so the API function will actually be a weak symbol, which means if the
+ * provider of the API is not loaded, the symbol can still be referenced (unlike a
  * strong symbol, which would cause an immediate fault if not defined when
  * referenced), but it will return NULL signifying the linker/loader was
  * not able to resolve the symbol. In addition, the macro defines a hidden
  * 'stub' version of the API call, using a provided function body, and uses
- * the alias attribute to make the API function symbol actually resolve to
+ * various methods to make the API function symbol actually resolve to
  * that hidden stub, but only when the *real* provider of the symbol has
  * not been found.
  *
@@ -57,13 +57,25 @@
  * safely know that the API is not available, and to avoid using any
  * other APIs from the not-present provider.
  *
+ * In addition to this declaration in the header file, the actual definition of
+ * the API function must use the AST_OPTIONAL_API_NAME macro to (possibly)
+ * modify the real name of the API function, depending on the specific
+ * implementation requirements. The corresponding example from res_agi.c:
+ *
+ * \code
+ * int AST_OPTIONAL_API_NAME(ast_agi_register)(struct ast_module *mod, agi_command *cmd)
+ * {
+ * ...
+ * }
+ * \endcode
+ *
  * In the module providing the API, the AST_OPTIONAL_API macro must
  * be informed that it should not build the hidden stub function or
  * apply special aliases to the function prototype; this can be done
  * by defining AST_API_MODULE just before including the header file
  * containing the AST_OPTIONAL_API macro calls.
  *
- * \note If the GCC 'weak' and 'alias' attributes are not available,
+ * \note If the platform does not provide adequate resources,
  * then the AST_OPTIONAL_API macro will result in a non-optional function
  * definition; this means that any consumers of the API functions so
  * defined will require that the provider of the API functions be
@@ -83,17 +95,115 @@
  */
 #define AST_OPTIONAL_API_UNAVAILABLE	INT_MIN
 
-#if defined(HAVE_ATTRIBUTE_weak_import) && !defined(AST_API_MODULE)
-#define AST_OPTIONAL_API(result, name, proto, stub)	result name proto __attribute__((weak_import));
-#define AST_OPTIONAL_API_ATTR(result, attr, name, proto, stub)	result name proto __attribute__((weak_import,attr));
-#elif defined(HAVE_ATTRIBUTE_weak) && defined(HAVE_ATTRIBUTE_alias) && !defined(AST_API_MODULE) && !defined(HAVE_ATTRIBUTE_weak_import)
-#define AST_OPTIONAL_API(result, name, proto, stub)	\
-	static result __##name proto stub;		\
-	result __attribute__((weak, alias("__" __stringify(name)))) name proto;
-#define AST_OPTIONAL_API_ATTR(result, attr, name, proto, stub)		\
-	static result __attribute__((attr)) __##name proto stub;	\
-	result __attribute__((weak, alias("__" __stringify(name)), attr)) name proto;
+
+#if defined(HAVE_ATTRIBUTE_weak_import)
+
+/*
+ * This is the Darwin (Mac OS/X) implementation, that only provides the
+ * 'weak_import' compiler attribute for weak symbols. On this platform,
+ *
+ * - The module providing the API will only provide a '__' prefixed version
+ *   of the API function to other modules (this will be hidden from the other
+ *   modules by the macros), so any modules compiled against older versions
+ *   of the module that provided a non-prefixed version of the API function
+ *   will fail to link at runtime.
+ * - In the API module itself, access to the API function without using a
+ *   prefixed name is provided by a static pointer variable that holds the
+ *   function address.
+ * - 'Consumer' modules of the API will use a combination of a weak_import
+ *   symbol, a local stub function, a pointer variable and a constructor function
+ *   (which initializes that pointer variable as the module is being loaded)
+ *   to provide safe, optional access to the API function without any special
+ *   code being required.
+ */
+
+#define AST_OPTIONAL_API_NAME(name) __##name
+
+#if defined(AST_API_MODULE)
+
+#define AST_OPTIONAL_API(result, name, proto, stub) \
+	result AST_OPTIONAL_API_NAME(name) proto; \
+	static attribute_unused typeof(AST_OPTIONAL_API_NAME(name)) * const name = AST_OPTIONAL_API_NAME(name);
+
+#define AST_OPTIONAL_API_ATTR(result, attr, name, proto, stub)	\
+	result __attribute__((attr)) AST_OPTIONAL_API_NAME(name) proto; \
+	static attribute_unused typeof(AST_OPTIONAL_API_NAME(name)) * const name = AST_OPTIONAL_API_NAME(name);
+
+#else
+
+#define AST_OPTIONAL_API(result, name, proto, stub) \
+	static result __stub__##name proto stub; \
+	__attribute__((weak_import)) typeof(__stub__##name) AST_OPTIONAL_API_NAME(name); \
+	static attribute_unused typeof(__stub__##name) * name; \
+	static void __attribute__((constructor)) __init__##name(void) { name = AST_OPTIONAL_API_NAME(name) ? : __stub__##name; }
+
+#define AST_OPTIONAL_API_ATTR(result, attr, name, proto, stub) \
+	static __attribute__((attr)) result __stub__##name proto stub; \
+	__attribute__((attr, weak_import)) typeof(__stub__##name) AST_OPTIONAL_API_NAME(name); \
+	static attribute_unused __attribute__((attr)) typeof(__stub__##name) * name; \
+	static void __attribute__((constructor)) __init__##name(void) { name = AST_OPTIONAL_API_NAME(name) ? : __stub__##name; }
+
+
+#endif
+
+/* End of Darwin (Mac OS/X) implementation */
+
+#elif defined(HAVE_ATTRIBUTE_weakref)
+
+/*
+ * This is the generic GCC implementation, used when the 'weakref'
+ * compiler attribute is available. On these platforms:
+ *
+ * - The module providing the API will provide a '__' prefixed version
+ *   of the API function to other modules (this will be hidden from the other
+ *   modules by the macros), and also a non-prefixed alias so that modules
+ *   compiled against older versions of the module that provided a non-prefixed
+ *    version of the API function will continue to link properly.
+ * - In the API module itself, access to the API function without using a
+ *   prefixed name is provided by the non-prefixed alias described above.
+ * - 'Consumer' modules of the API will use a combination of a weakref
+ *   symbol, a local stub function, a pointer variable and a constructor function
+ *   (which initializes that pointer variable as the module is being loaded)
+ *   to provide safe, optional access to the API function without any special
+ *   code being required.
+ */
+
+#define AST_OPTIONAL_API_NAME(name) __##name
+
+#if defined(AST_API_MODULE)
+
+#define AST_OPTIONAL_API(result, name, proto, stub) \
+	result AST_OPTIONAL_API_NAME(name) proto; \
+	__attribute__((alias(__stringify(AST_OPTIONAL_API_NAME(name))))) typeof(AST_OPTIONAL_API_NAME(name)) name;
+
+#define AST_OPTIONAL_API_ATTR(result, attr, name, proto, stub)	\
+	result __attribute__((attr)) AST_OPTIONAL_API_NAME(name) proto; \
+	__attribute__((alias(__stringify(AST_OPTIONAL_API_NAME(name))))) typeof(AST_OPTIONAL_API_NAME(name)) name;
+
+#else
+
+#define AST_OPTIONAL_API(result, name, proto, stub) \
+	static result __stub__##name proto stub; \
+	static __attribute__((weakref(__stringify(AST_OPTIONAL_API_NAME(name))))) typeof(__stub__##name) __ref__##name; \
+	static attribute_unused typeof(__stub__##name) * name; \
+	static void __attribute__((constructor)) __init__##name(void) { name = __ref__##name ? : __stub__##name; }
+
+#define AST_OPTIONAL_API_ATTR(result, attr, name, proto, stub) \
+	static __attribute__((attr)) result __stub__##name proto stub; \
+	static __attribute__((attr, weakref(__stringify(AST_OPTIONAL_API_NAME(name))))) typeof(__stub__##name) __ref__##name; \
+	static attribute_unused __attribute__((attr)) typeof(__stub__##name) * name; \
+	static void __attribute__((constructor)) __init__##name(void) { name = __ref__##name ? : __stub__##name; }
+
+#endif
+
+/* End of GCC implementation */
+
 #else
+
+/* This is the non-optional implementation. */
+
+#define AST_OPTIONAL_API_NAME(name) name
+
 /*!
  * \brief Define an optional API function
  *
@@ -108,7 +218,8 @@
  *                  { return AST_OPTIONAL_API_UNAVAILABLE; });
  * \endcode		 
  */
-#define AST_OPTIONAL_API(result, name, proto, stub) result name proto;
+#define AST_OPTIONAL_API(result, name, proto, stub) result AST_OPTIONAL_API_NAME(name) proto
+
 /*!
  * \brief Define an optional API function with compiler attributes
  *
@@ -118,7 +229,10 @@
  * \param proto The prototype (arguments) of the function
  * \param stub The code block that will be used by the hidden stub when needed
  */
-#define AST_OPTIONAL_API_ATTR(result, attr, name, proto, stub) result __attribute__((attr)) name proto;
+#define AST_OPTIONAL_API_ATTR(result, attr, name, proto, stub) result __attribute__((attr)) AST_OPTIONAL_API_NAME(name) proto
+
+/* End of non-optional implementation */
+
 #endif
 
 #undef AST_API_MODULE