simplify (and document!) macro for inlinable API functions (inspired by bug #4603, with slightly different implementation)

git-svn-id: http://svn.digium.com/svn/asterisk/trunk@6090 f38db490-d61c-443f-a65b-d21fe96a405b

4 files changed, 75 insertions, 38 deletions

diff --git a/include/asterisk/inline_api.h b/include/asterisk/inline_api.h
new file mode 100755
index 000000000..217f3be3f
--- /dev/null
+++ b/include/asterisk/inline_api.h
@@ -0,0 +1,57 @@
+/*
+ * Asterisk -- A telephony toolkit for Linux.
+ *
+ * Inlinable API function macro
+ *
+ * Copyright (C) 2005, Digium, Inc.
+ *
+ * This program is free software, distributed under the terms of
+ * the GNU General Public License
+ */
+
+#ifndef __ASTERISK_INLINEAPI_H
+#define __ASTERISK_INLINEAPI_H
+
+/*
+  Small API functions that are candidates for inlining need to be specially
+  declared and defined, to ensure that the 'right thing' always happens.
+  For example:
+  	- there must _always_ be a non-inlined version of the function
+	available for modules compiled out of the tree to link to
+	- references to a function that cannot be inlined (for any
+	reason that the compiler deems proper) must devolve into an
+	'extern' reference, instead of 'static', so that multiple
+	copies of the function body are not built in different modules
+	- when LOW_MEMORY is defined, inlining should be disabled
+	completely, even if the compiler is configured to support it
+
+  The AST_INLINE_API macro allows this to happen automatically, when
+  used to define your function. Proper usage is as follows:
+  - define your function one place, in a header file, using the macro
+  to wrap the function (see strings.h or time.h for examples)
+  - choose a module to 'host' the function body for non-inline
+  usages, and in that module _only_, define AST_API_MODULE before
+  including the header file
+ */
+
+#if !defined(LOW_MEMORY)
+
+#if !defined(AST_API_MODULE)
+#define AST_INLINE_API(hdr, body) hdr; extern inline hdr body
+#else
+#define AST_INLINE_API(hdr, body) hdr; hdr body
+#endif
+
+#else /* defined(LOW_MEMORY) */
+
+#if !defined(AST_API_MODULE)
+#define AST_INLINE_API(hdr, body) hdr;
+#else
+#define AST_INLINE_API(hdr, body) hdr; hdr body
+#endif
+
+#endif
+
+#undef AST_API_MODULE
+
+#endif /* __ASTERISK_INLINEAPI_H */
diff --git a/include/asterisk/strings.h b/include/asterisk/strings.h
index eee85a551..4fef8691c 100755
--- a/include/asterisk/strings.h
+++ b/include/asterisk/strings.h
@@ -14,6 +14,7 @@
 
 #include <string.h>
 
+#include "asterisk/inline_api.h"
 #include "asterisk/compiler.h"
 
 static inline int ast_strlen_zero(const char *s)
@@ -26,30 +27,22 @@ static inline int ast_strlen_zero(const char *s)
   \param str the input string
   \return a pointer to the first non-whitespace character
  */
-char *ast_skip_blanks(char *str);
-#if !defined(LOW_MEMORY) && !defined(AST_API_MODULE)
-extern inline
-#endif
-#if !defined(LOW_MEMORY) || defined(AST_API_MODULE)
-char *ast_skip_blanks(char *str)
+AST_INLINE_API(
+char *ast_skip_blanks(char *str),
 {
 	while (*str && *str < 33)
 		str++;
 	return str;
 }
-#endif
+)
 
 /*!
   \brief Trims trailing whitespace characters from a string.
   \param str the input string
   \return a pointer to the NULL following the string
  */
-char *ast_trim_blanks(char *str);
-#if !defined(LOW_MEMORY) && !defined(AST_API_MODULE)
-extern inline
-#endif
-#if !defined(LOW_MEMORY) || defined(AST_API_MODULE)
-char *ast_trim_blanks(char *str)
+AST_INLINE_API(
+char *ast_trim_blanks(char *str),
 {
 	char *work = str;
 
@@ -66,25 +59,21 @@ char *ast_trim_blanks(char *str)
 	}
 	return str;
 }
-#endif
+)
 
 /*!
   \brief Gets a pointer to first whitespace character in a string.
   \param str the input string
   \return a pointer to the first whitespace character
  */
-char *ast_skip_nonblanks(char *str);
-#if !defined(LOW_MEMORY) && !defined(AST_API_MODULE)
-extern inline
-#endif
-#if !defined(LOW_MEMORY) || defined(AST_API_MODULE)
-char *ast_skip_nonblanks(char *str)
+AST_INLINE_API(
+char *ast_skip_nonblanks(char *str),
 {
 	while (*str && *str > 32)
 		str++;
 	return str;
 }
-#endif
+)
   
 /*!
   \brief Strip leading/trailing whitespace from a string.
@@ -95,19 +84,15 @@ char *ast_skip_nonblanks(char *str)
   characters from the input string, and returns a pointer to
   the resulting string. The string is modified in place.
 */
-char *ast_strip(char *s);
-#if !defined(LOW_MEMORY) && !defined(AST_API_MODULE)
-extern inline
-#endif
-#if !defined(LOW_MEMORY) || defined(AST_API_MODULE)
-char *ast_strip(char *s)
+AST_INLINE_API(
+char *ast_strip(char *s),
 {
 	s = ast_skip_blanks(s);
 	if (s)
 		ast_trim_blanks(s);
 	return s;
 } 
-#endif
+)
 
 /*!
   \brief Strip leading/trailing whitespace and quotes from a string.
@@ -222,5 +207,4 @@ struct ast_realloca {
 extern char *ast_strcasestr(const char *, const char *);
 #endif /* __linux__ */
 
-#undef AST_API_MODULE
 #endif /* _ASTERISK_STRINGS_H */
diff --git a/include/asterisk/time.h b/include/asterisk/time.h
index b34ff4f61..ec7a51d8d 100755
--- a/include/asterisk/time.h
+++ b/include/asterisk/time.h
@@ -14,22 +14,19 @@
 
 #include <sys/time.h>
 
+#include "asterisk/inline_api.h"
+
 /*!
  * \brief Computes the difference (in milliseconds) between two \c struct \c timeval instances.
  * \param end the beginning of the time period
  * \param start the end of the time period
  * \return the difference in milliseconds
  */
-int ast_tvdiff_ms(const struct timeval *end, const struct timeval *start);
-#if !defined(LOW_MEMORY) && !defined(AST_API_MODULE)
-extern inline
-#endif
-#if !defined(LOW_MEMORY) || defined(AST_API_MODULE)
-int ast_tvdiff_ms(const struct timeval *end, const struct timeval *start)
+AST_INLINE_API(
+int ast_tvdiff_ms(const struct timeval *end, const struct timeval *start),
 {
 	return ((end->tv_sec - start->tv_sec) * 1000) + ((end->tv_usec - start->tv_usec) / 1000);
 }
-#endif
+)
 
-#undef AST_API_MODULE
 #endif /* _ASTERISK_TIME_H */
diff --git a/include/asterisk/utils.h b/include/asterisk/utils.h
index 7449c1d6e..246da5e76 100755
--- a/include/asterisk/utils.h
+++ b/include/asterisk/utils.h
@@ -148,5 +148,4 @@ extern int ast_wait_for_input(int fd, int ms);
 #define ast_pthread_create(a,b,c,d) ast_pthread_create_stack(a,b,c,d,0)
 extern int ast_pthread_create_stack(pthread_t *thread, pthread_attr_t *attr, void *(*start_routine)(void *), void *data, size_t stacksize);
 
-#undef AST_API_MODULE
 #endif /* _ASTERISK_UTILS_H */