optional_api.c File Reference

#include "asterisk.h"
#include "asterisk/optional_api.h"
#include "asterisk/utils.h"
#include "asterisk/vector.h"

Include dependency graph for optional_api.c:

Go to the source code of this file.

Data Structures
struct	optional_api
	An optional API. More...
struct	optional_api_user
	A user of an optional API. More...

Macros
#define	OPTIONAL_API_SYMNAME_CMP(ele, value)   (!strcmp(ele->symname, value))
#define	USER_OPTIONAL_REF_CMP(ele, value)   (ele->optional_ref == value)

Functions
void	ast_optional_api_provide (const char *symname, ast_optional_fn impl)
void	ast_optional_api_unprovide (const char *symname, ast_optional_fn impl)
void	ast_optional_api_unuse (const char *symname, ast_optional_fn *optional_ref, const char *module)
void	ast_optional_api_use (const char *symname, ast_optional_fn *optional_ref, ast_optional_fn stub, const char *module)
	AST_VECTOR (struct optional_api *)
	Free an optional_api_user. More...
static struct optional_api *	get_api (const char *symname)
	Gets (or creates) the optional_api for the given function. More...
static struct optional_api *	optional_api_create (const char *symname)
	Create and link an optional_api. More...
static void	optional_api_destroy (struct optional_api *api)
	Free an optional_api. More...
static void	optional_api_set_impl (struct optional_api *api, ast_optional_fn impl)
	Sets the implementation function pointer for an api. More...
static struct optional_api_user *	optional_api_user_create (ast_optional_fn *optional_ref, ast_optional_fn stub, const char *module)
	Create an optional_api_user. More...
static void	optional_api_user_relink (struct optional_api_user *user, struct optional_api *api)
	Re-links a given user against its associated api. More...

Macro Definition Documentation

OPTIONAL_API_SYMNAME_CMP

#define OPTIONAL_API_SYMNAME_CMP	(		ele,
			value
	)		(!strcmp(ele->symname, value))

Referenced by get_api().

USER_OPTIONAL_REF_CMP

#define USER_OPTIONAL_REF_CMP	(		ele,
			value
	)		(ele->optional_ref == value)

Referenced by ast_optional_api_unuse().

Function Documentation

ast_optional_api_provide()

void ast_optional_api_provide	(	const char *	symname,
		ast_optional_fn	impl
	)

Definition at line 212 of file optional_api.c.

References get_api(), and optional_api_set_impl().

Referenced by AST_TEST_DEFINE().

{
   struct optional_api *api;

   api = get_api(symname);
   if (api) {
      optional_api_set_impl(api, impl);
   }
}

ast_optional_api_unprovide()

void ast_optional_api_unprovide	(	const char *	symname,
		ast_optional_fn	impl
	)

Definition at line 222 of file optional_api.c.

References get_api(), and optional_api_set_impl().

Referenced by AST_TEST_DEFINE().

{
   struct optional_api *api;

   api = get_api(symname);
   if (api) {
      optional_api_set_impl(api, 0);
   }
}

ast_optional_api_unuse()

void ast_optional_api_unuse	(	const char *	symname,
		ast_optional_fn *	optional_ref,
		const char *	module
	)

Definition at line 257 of file optional_api.c.

References AST_VECTOR_REMOVE_CMP_UNORDERED, AST_VECTOR_SIZE, get_api(), optional_api::impl, optional_api_destroy(), and USER_OPTIONAL_REF_CMP.

Referenced by AST_TEST_DEFINE().

{
   struct optional_api *api;

   api = get_api(symname);
   if (api) {
      AST_VECTOR_REMOVE_CMP_UNORDERED(&api->users, optional_ref, USER_OPTIONAL_REF_CMP, optional_api_user_destroy);
      if (!api->impl && !AST_VECTOR_SIZE(&api->users)) {
         optional_api_destroy(api);
      }
   }
}

ast_optional_api_use()

void ast_optional_api_use	(	const char *	symname,
		ast_optional_fn *	optional_ref,
		ast_optional_fn	stub,
		const char *	module
	)

Definition at line 232 of file optional_api.c.

References ast_do_crash(), AST_VECTOR_APPEND, get_api(), optional_api_user_create(), optional_api_user_relink(), and user.

Referenced by AST_TEST_DEFINE().

{
   struct optional_api_user *user;
   struct optional_api *api;

   api = get_api(symname);
   if (!api) {
      return;
   }

   user = optional_api_user_create(optional_ref, stub, module);
   if (!user) {
      return;
   }

   /* Add user to the API */
   if (!AST_VECTOR_APPEND(&api->users, user)) {
      optional_api_user_relink(user, api);
   } else {
      optional_api_user_destroy(user);
      ast_do_crash();
   }
}

AST_VECTOR()

AST_VECTOR

(

struct optional_api *

)

Free an optional_api_user.

Vector of optional_api functions

Parameters

user	User struct to free.

Definition at line 67 of file optional_api.c.

References ast_free, optional_api_user::optional_ref, and optional_api_user::stub.

{
   *user->optional_ref = user->stub;
   ast_free(user);
}

get_api()

static struct optional_api* get_api ( const char *  symname )

static

Gets (or creates) the optional_api for the given function.

Parameters

sysname

Name of the function to look up.

Returns

Corresponding optional_api.

NULL on error.

Definition at line 158 of file optional_api.c.

References AST_VECTOR_GET_CMP, optional_api_create(), and OPTIONAL_API_SYMNAME_CMP.

Referenced by ast_optional_api_provide(), ast_optional_api_unprovide(), ast_optional_api_unuse(), and ast_optional_api_use().

{
   struct optional_api **api;

   /* Find one, if we already have it */
   api = AST_VECTOR_GET_CMP(&apis, symname, OPTIONAL_API_SYMNAME_CMP);
   if (api) {
      return *api;
   }

   /* API not found. Build one */
   return optional_api_create(symname);
}

optional_api_create()

static struct optional_api* optional_api_create ( const char *  symname )

static

Create and link an optional_api.

Parameters

symname

Name of the optional function.

Returns

New optional_api.

NULL on error.

Definition at line 134 of file optional_api.c.

References ast_calloc, ast_do_crash(), ast_free, AST_VECTOR_APPEND, and NULL.

Referenced by get_api().

{
   struct optional_api *api;

   api = ast_calloc(1, sizeof(*api) + strlen(symname) + 1);
   if (!api || AST_VECTOR_APPEND(&apis, api)) {
      ast_free(api);
      ast_do_crash();

      return NULL;
   }

   strcpy(api->symname, symname); /* SAFE */

   return api;
}

optional_api_destroy()

static void optional_api_destroy ( struct optional_api *  api )

static

Free an optional_api.

Parameters

api	API struct to free.

Definition at line 118 of file optional_api.c.

References ast_free, AST_VECTOR_CALLBACK_VOID, AST_VECTOR_ELEM_CLEANUP_NOOP, AST_VECTOR_ELEM_DEFAULT_CMP, AST_VECTOR_FREE, and AST_VECTOR_REMOVE_CMP_UNORDERED.

Referenced by ast_optional_api_unuse(), and optional_api_set_impl().

{
   AST_VECTOR_REMOVE_CMP_UNORDERED(&apis, api,
      AST_VECTOR_ELEM_DEFAULT_CMP, AST_VECTOR_ELEM_CLEANUP_NOOP);
   AST_VECTOR_CALLBACK_VOID(&api->users, optional_api_user_destroy);
   AST_VECTOR_FREE(&api->users);
   ast_free(api);
}

optional_api_set_impl()

static void optional_api_set_impl ( struct optional_api *  api, ast_optional_fn  impl  )

static

Sets the implementation function pointer for an api.

Parameters

api	API to implement/stub out.
impl	Pointer to implementation function. Can be 0 to remove implementation.

Definition at line 198 of file optional_api.c.

References AST_VECTOR_CALLBACK_VOID, AST_VECTOR_SIZE, optional_api::impl, optional_api_destroy(), and optional_api_user_relink().

Referenced by ast_optional_api_provide(), and ast_optional_api_unprovide().

{
   api->impl = impl;

   /* re-link all users */
   if (AST_VECTOR_SIZE(&api->users)) {
      AST_VECTOR_CALLBACK_VOID(&api->users, optional_api_user_relink, api);
   } else if (!impl) {
      /* No users or impl means we should delete this api. */
      optional_api_destroy(api);
   }
}

optional_api_user_create()

static struct optional_api_user* optional_api_user_create ( ast_optional_fn *  optional_ref, ast_optional_fn  stub, const char *  module  )

static

Create an optional_api_user.

Parameters

optional_ref	Pointer-to-function-pointer to link to impl/stub.
stub	Stub function to link to when impl is not available.
module	Name of the module requesting the API.

Returns

New optional_api_user.

NULL on error.

Definition at line 93 of file optional_api.c.

References ast_calloc, ast_do_crash(), optional_api_user::module, NULL, optional_api_user::optional_ref, optional_api_user::stub, and user.

Referenced by ast_optional_api_use().

{
   struct optional_api_user *user;
   size_t size = sizeof(*user) + strlen(module) + 1;

   user = ast_calloc(1, size);
   if (!user) {
      ast_do_crash();

      return NULL;
   }

   user->optional_ref = optional_ref;
   user->stub = stub;
   strcpy(user->module, module); /* SAFE */

   return user;
}

optional_api_user_relink()

static void optional_api_user_relink ( struct optional_api_user *  user, struct optional_api *  api  )

static

Re-links a given user against its associated api.

If the api has an implementation, the user is linked to that implementation. Otherwise, the user is linked to its stub.

Parameters

user	optional_api_user to link.
api	optional_api to link.

Definition at line 181 of file optional_api.c.

References optional_api::impl, optional_api_user::optional_ref, and optional_api_user::stub.

Referenced by ast_optional_api_use(), and optional_api_set_impl().

{
   if (api->impl && *user->optional_ref != api->impl) {
      *user->optional_ref = api->impl;
   } else if (!api->impl && *user->optional_ref != user->stub) {
      *user->optional_ref = user->stub;
   }
}