Bus Backend Management

Functions
int	amxb_be_register (amxb_be_funcs_t *const funcs)
	Registers backend interface. More...
int	amxb_be_unregister (amxb_be_funcs_t *const funcs)
	Unregisters a backend interface. More...
amxb_be_funcs_t *	amxb_be_find (const char *name)
	Gets a backend function table using its name. More...
const amxb_be_info_t *	amxb_be_get_info (const char *name)
	Gets a backend information. More...
int	amxb_be_load (const char *path_name)
	Loads a shared object that implements a bus specific backend interface. More...
int	amxb_be_load_multiple (amxc_var_t *const bes)
	Loads multiple shared objects that each implement a bus specific backend interface. More...
int	amxb_be_remove (const char *backend_name)
	Removes and unloads a backend with a given name. More...
void	amxb_be_remove_all (void)
	Removes and unloads all backends. More...
amxc_array_t *	amxb_be_list (void)
	Get the loaded back-end names. More...
int	amxb_be_for_all_connections (amxb_be_task_fn_t fn, const amxc_var_t *args, void *priv)
	Calls a function on all open connections. More...
int	amxb_be_for_all_listeners (amxb_be_task_fn_t fn, const amxc_var_t *args, void *priv)
	Calls a function on all listen sockets. More...
amxb_bus_ctx_t *	amxb_be_who_has (const char *object_path)
	Searches a bus context that can provide a certain object. More...
void	amxb_be_cache_remove_ctx (amxb_bus_ctx_t *ctx)
	Removes a bus context from the lookup cache. More...
void	amxb_be_cache_remove_path (const char *object_path)
	Removes an object path and its corresponding bus context from the lookup cache. More...
void	amxb_be_cache_set_size (uint32_t size)
	Changes the size of the lookup cache. More...
int	amxb_set_config (amxc_var_t *const configuration)
	Passes configuration options to the backends. More...
int	amxb_check_version (const amxb_version_t *be_version)
	Compares the given version with the library version. More...
int	amxb_check_be_versions (const amxb_version_t *min, const amxb_version_t *max)
	Checks if the library version is in the given range. More...
const amxb_version_t *	amxb_get_version (void)
	Gets the version of the library. More...

Detailed Description

Function Documentation

amxb_be_cache_remove_ctx()

void amxb_be_cache_remove_ctx

(

amxb_bus_ctx_t *

ctx

)

Removes a bus context from the lookup cache.

Bus contexts are added to the lookup cache by amxb_be_who_has

Parameters

ctx	a bus context

Definition at line 654 of file amxb_backend_mngr.c.

                                                   {
    when_null(ctx, exit);
 
    amxc_llist_for_each(lit, &amxb_cache_list) {
        amxb_who_has_cache_t* cache = amxc_container_of(lit, amxb_who_has_cache_t, lit);
        if(cache->ctx == ctx) {
            amxc_llist_it_take(&cache->lit);
            amxc_htable_it_clean(&cache->hit, NULL);
            free(cache);
        }
    }
 
exit:
    return;
}

amxb_be_cache_remove_path()

void amxb_be_cache_remove_path

(

const char *

object_path

)

Removes an object path and its corresponding bus context from the lookup cache.

Bus contexts are added to the lookup cache by amxb_be_who_has

Parameters

object_path

Object path that must be removed from the cache

Definition at line 670 of file amxb_backend_mngr.c.

                                                        {
    amxc_htable_it_t* cache_hit = NULL;
    amxb_who_has_cache_t* cache = NULL;
 
    when_str_empty(object_path, exit);
    when_true(strcmp(object_path, ".") == 0, exit);
 
    cache_hit = amxc_htable_get(&amxb_cache_table, object_path);
    when_null(cache_hit, exit);
 
    cache = amxc_container_of(cache_hit, amxb_who_has_cache_t, hit);
    amxc_llist_it_take(&cache->lit);
    amxc_htable_it_clean(&cache->hit, NULL);
    free(cache);
 
exit:
    return;
}

amxb_be_cache_set_size()

void amxb_be_cache_set_size

(

uint32_t

size

)

Changes the size of the lookup cache.

Bus contexts are added to the lookup cache by amxb_be_who_has.

When the new size is smaller then the current size, the oldes entries are removed from the cache.

Parameters

size	the new size

Definition at line 689 of file amxb_backend_mngr.c.

                                           {
    uint32_t items = amxc_htable_size(&amxb_cache_table);
    if(size < items) {
        amxc_llist_for_each_reverse(it, &amxb_cache_list) {
            amxb_who_has_cache_t* cache = amxc_container_of(it, amxb_who_has_cache_t, lit);
            amxc_llist_it_take(&cache->lit);
            amxc_htable_it_clean(&cache->hit, NULL);
            free(cache);
            items--;
            if(size >= items) {
                break;
            }
        }
    }
 
    amxb_cache_size = size;
}

amxb_be_find()

amxb_be_funcs_t* amxb_be_find

(

const char *

name

)

Gets a backend function table using its name.

This function is mainly used internally to fetch the function table of a specific backend.

Note

Do not free the returned pointer or store the pointer. The backend function table can be removed at any time. Always use this function to retrieve the function table pointer.

Parameters

name	name of the backend

Returns

returns NULL when no backend with the given name is found. Otherwise it returns the function table pointer.

Definition at line 432 of file amxb_backend_mngr.c.

                                                {
    amxb_be_funcs_t* fns = NULL;
    amxc_htable_it_t* hit = NULL;
 
    when_null(name, exit);
    when_true(*(name) == 0, exit);
 
    hit = amxc_htable_get(&amxb_backends, name);
    when_null(hit, exit);
 
    fns = amxc_htable_it_get_data(hit, amxb_be_funcs_t, it);
 
exit:
    return fns;
}

amxb_be_for_all_connections()

int amxb_be_for_all_connections	(	amxb_be_task_fn_t	fn,
		const amxc_var_t *	args,
		void *	priv
	)

Calls a function on all open connections.

Loops over all backends and calls a functions for each open connection for the backend.

Parameters

fn	function to be called
args	a variant that is passed to the function
priv	some private data, is passed as is to the function

Returns

0 when at least one connection could perform the task

Definition at line 610 of file amxb_backend_mngr.c.

                                            {
    int retval = AMXB_ERROR_UNKNOWN;
    when_null(fn, exit);
 
    amxc_htable_for_each(hit, &amxb_backends) {
        amxb_be_funcs_t* funcs = amxc_htable_it_get_data(hit, amxb_be_funcs_t, it);
        if(amxb_be_invoke_on_all_connections(&funcs->connections,
                                             fn,
                                             args,
                                             AMXB_DATA_SOCK,
                                             priv) == AMXB_STATUS_OK) {
            retval = AMXB_STATUS_OK;
        }
    }
 
exit:
    return retval;
}

amxb_be_for_all_listeners()

int amxb_be_for_all_listeners	(	amxb_be_task_fn_t	fn,
		const amxc_var_t *	args,
		void *	priv
	)

Calls a function on all listen sockets.

Loops over all backends and calls a functions for each listen socket for the backend.

Parameters

fn	function to be called
args	a variant that is passed to the function
priv	some private data, is passed as is to the function

Returns

0 when no errors occured

Definition at line 631 of file amxb_backend_mngr.c.

                                          {
    int retval = 0;
    when_null(fn, exit);
 
    amxc_htable_for_each(hit, &amxb_backends) {
        amxb_be_funcs_t* funcs = amxc_htable_it_get_data(hit, amxb_be_funcs_t, it);
        retval = amxb_be_invoke_on_all_connections(&funcs->connections,
                                                   fn,
                                                   args,
                                                   AMXB_LISTEN_SOCK,
                                                   priv);
    }
 
exit:
    return retval;
}

amxb_be_get_info()

const amxb_be_info_t* amxb_be_get_info

(

const char *

name

)

Gets a backend information.

Fetches some meta-information from the backend.

Note

Do not free the returned pointer or store the pointer.

Parameters

name	name of the backend

Returns

returns NULL when no backend with the given name is found. Otherwise it returns the function table pointer.

Definition at line 448 of file amxb_backend_mngr.c.

                                                         {
    amxb_be_funcs_t* fns = NULL;
    amxb_be_info_fn_t be_get_info = NULL;
    amxb_be_info_t* info = NULL;
    amxc_htable_it_t* hit = NULL;
 
    when_null(name, exit);
    when_true(*(name) == 0, exit);
 
    hit = amxc_htable_get(&amxb_backends, name);
    when_null(hit, exit);
 
    fns = amxc_htable_it_get_data(hit, amxb_be_funcs_t, it);
 
    be_get_info = (amxb_be_info_fn_t) dlsym(fns->handle, "amxb_be_info");
    when_null(be_get_info, exit);
    info = be_get_info();
 
exit:
    return info;
}

amxb_be_list()

amxc_array_t* amxb_be_list

(

void

)

Get the loaded back-end names.

This function returns an array of pointers to the loaded back-end names. You can iterate over this array using a simple for loop.

Example:

void dump_backend_names(void) {
   amxc_array_t* names = amxb_be_list();
   size_t size = amxc_array_size(names);
 
   for(size_t i = 0; i < size; i++) {
      const char* name = (const char *)amxc_array_get_data_at(names, i);
      printf("back-end [%s]\n", name);
   }
 
   amxc_array_delete(&names, NULL);
}

The array must be freed when not needed any more, use amxc_array_delete.

Warning

Do not free the content of the array, in other words do not provide a delete callback to amxc_array_delete.

Returns

returns a pointer to an amxc_array_t.

Definition at line 606 of file amxb_backend_mngr.c.

                                 {
    return amxc_htable_get_sorted_keys(&amxb_backends);
}

amxb_be_load()

int amxb_be_load

(

const char *

path_name

)

Loads a shared object that implements a bus specific backend interface.

Loads a shared object into memory using dlopen. It is assumed that the shared object provides a backend interface implementation.

The symbol "amxb_be_info" is resolved using dlsym. If the shared object does not contain this symbol, the shared object is closed and the loading fails.

The function "amxb_be_info" is called and must return a backend information structure which must contain the minimum and maximum supported version of this library. If the version of this library is not within the range, the shared object is closed and loading fails.

Parameters

path_name

absolute or relative path to a shared object that implements a backend interface

Returns

returns 0 when the shared object is loaded successfully and it provides a valid backend interface.

Definition at line 470 of file amxb_backend_mngr.c.

                                        {
    int retval = -1;
    void* handle = NULL;
    amxb_be_info_fn_t be_get_info = NULL;
    amxb_be_info_t* be_info = NULL;
    when_str_empty(path_name, exit);
 
    // Set current backend functions to NULL.
    // If the loaded shared object has a construct that calls amxb_be_register
    // the current_be will be set correctly.
    // This happends during the dlopen
    current_be = NULL;
    handle = dlopen(path_name, RTLD_LAZY);
    if(handle == NULL) {
        const char* errstr = dlerror();
        printf("DLOPEN - %s\n", errstr != NULL? errstr:"no error");
        goto exit;
    }
 
    be_get_info = (amxb_be_info_fn_t) dlsym(handle, "amxb_be_info");
    when_null(be_get_info, exit);
 
    be_info = be_get_info();
    when_null(be_info, exit);
    when_null(be_info->min_supported, exit);
    when_null(be_info->max_supported, exit);
 
    when_failed(amxb_check_be_versions(be_info->min_supported,
                                       be_info->max_supported), exit);
 
    when_true(amxb_check_version(be_info->min_supported) < 0, exit);
    when_true(amxb_check_version(be_info->max_supported) > 0, exit);
 
    // The loaded back-end could call amxb_be_register using a constructor
    // function. This method is not always reliable, depending on the platform
    // the constructor is not invoked.
    // Or the back-end did not call amxb_be_register function
 
    // Prefered solution is that the backend gives the function table using
    // the back-end information structure. The following lines are here for
    // backwards compatibility.
    if(current_be == NULL) {
        when_null(be_info->funcs, exit);
        if(be_info->funcs->handle == handle) {
            dlclose(handle);
        } else if(be_info->funcs->handle != NULL) {
            goto exit;
        } else {
            when_failed(amxb_be_register(be_info->funcs), exit);
        }
    } else {
        be_info->funcs = current_be;
    }
 
    be_info->funcs->handle = handle;
 
    retval = 0;
 
exit:
    if((retval != 0) && (handle != NULL)) {
        dlclose(handle);
    }
    current_be = NULL;
    return retval;
}

amxb_be_load_multiple()

int amxb_be_load_multiple

(

amxc_var_t *const

bes

)

Loads multiple shared objects that each implement a bus specific backend interface.

The variant may contain a string or a linked list.

When the variant contains a string it will be split using ':' as a separator. Each individual part is assumed to be an absolute or relative path to a shared object file.

If it is a variant containing a list of variants, each variant in the list must contain an absolute or relative path to a shared object file.

When one or more shared objects can not be loaded, the function will load all other shared objects.

Parameters

bes	list of backends

Returns

returns the number of backends that failed to load

Definition at line 536 of file amxb_backend_mngr.c.

                                                 {
    int retval = -1;
    const amxc_llist_t* list = NULL;
    amxc_llist_t list_bes;
 
    amxc_llist_init(&list_bes);
 
    when_null(bes, exit);
    when_true(amxc_var_type_of(bes) != AMXC_VAR_ID_LIST &&
              amxc_var_type_of(bes) != AMXC_VAR_ID_CSTRING, exit);
 
 
    if(amxc_var_type_of(bes) == AMXC_VAR_ID_CSTRING) {
        amxc_string_t* str_bes = amxc_var_take(amxc_string_t, bes);
        when_null(str_bes, exit);
        amxc_string_split_to_llist(str_bes, &list_bes, ':');
        amxc_var_clean(bes);
        amxc_var_set_type(bes, AMXC_VAR_ID_LIST);
        amxc_llist_for_each(it, (&list_bes)) {
            amxc_string_t* str = amxc_string_from_llist_it(it);
            amxc_var_add(cstring_t, bes, amxc_string_get(str, 0));
        }
        amxc_string_delete(&str_bes);
    }
    list = amxc_var_constcast(amxc_llist_t, bes);
 
    when_true(amxc_llist_is_empty(list), exit);
    retval = 0;
    amxc_llist_for_each(it, list) {
        amxc_var_t* be = amxc_var_from_llist_it(it);
        if(amxb_be_load(amxc_var_constcast(cstring_t, be)) == 0) {
            amxc_var_delete(&be);
        } else {
            retval++;
        }
    }
 
exit:
    amxc_llist_clean(&list_bes, amxc_string_list_it_free);
    return retval;
}

amxb_be_register()

int amxb_be_register

(

amxb_be_funcs_t *const

funcs

)

Registers backend interface.

Backend can call this function to register the function table (backend interface) in a constructor function.

The preferred solution however is backend provides the function table using "amxb_be_info" which returns the backend information, this information may contain the function table.

The function table must contain at least:

• A valid and unique backend name
• The size filled in the stucture must be smaller or equal to the sizeof(amxb_be_funcs_t)
• And the following function pointers must be set:
  • connect
  • disconnect
  • get_fd
  • read

When the backend provides the function "set_config" it will be called if backend specific configuration options are available.

Parameters

funcs

The back-end function table

Returns

returns 0 when the function table is accepted.

Definition at line 372 of file amxb_backend_mngr.c.

                                                   {
    int retval = -1;
    amxc_htable_it_t* hit = NULL;
 
    when_null(funcs, exit);
    when_null(funcs->name, exit);
    when_true(*(funcs->name) == 0, exit);
    when_true(funcs->size > sizeof(amxb_be_funcs_t), exit);
 
    if(amxc_htable_is_empty(&amxb_backends)) {
        when_failed(amxc_htable_init(&amxb_backends, 10), exit);
    } else {
        hit = amxc_htable_get(&amxb_backends, funcs->name);
        when_not_null(hit, exit);
    }
 
    current_be = funcs;
    funcs->handle = NULL;
 
    amxc_htable_it_init(&funcs->it);
    amxc_llist_init(&funcs->connections);
    when_failed(amxc_htable_insert(&amxb_backends, funcs->name, &funcs->it), exit);
 
    if(amxb_conf != NULL) {
        amxc_var_t* cfg = amxc_var_get_key(amxb_conf, funcs->name, AMXC_VAR_FLAG_DEFAULT);
        amxb_apply_be_config(funcs, cfg);
    }
 
    retval = 0;
 
exit:
    return retval;
}

amxb_be_remove()

int amxb_be_remove

(

const char *

backend_name

)

Removes and unloads a backend with a given name.

Before the backend is unloaded all connections that are opened using that backend are closed.

All bus contexts related to that backend will be invalid after this function call.

Parameters

backend_name

name of the backend

Returns

returns 0 when the backend is unloaded.

Definition at line 578 of file amxb_backend_mngr.c.

                                             {
    amxb_be_funcs_t* fns = NULL;
    amxc_htable_it_t* hit = NULL;
    int retval = -1;
 
    when_str_empty(backend_name, exit);
 
    hit = amxc_htable_get(&amxb_backends, backend_name);
    when_null(hit, exit);
 
    fns = amxc_htable_it_get_data(hit, amxb_be_funcs_t, it);
    when_null(fns->handle, exit);
    amxc_llist_clean(&fns->connections, amxb_be_remove_connections);
    amxc_htable_it_clean(hit, NULL);
 
    retval = amxb_close_backend(fns);
 
exit:
    if(amxc_htable_is_empty(&amxb_backends)) {
        amxc_htable_clean(&amxb_backends, NULL);
    }
    return retval;
}

amxb_be_remove_all()

void amxb_be_remove_all

(

void

)

Removes and unloads all backends.

Before the backends are unloaded all connections are closed

Typically this function is used just before the application exits.

Definition at line 602 of file amxb_backend_mngr.c.

                              {
    amxc_htable_clean(&amxb_backends, amxb_be_remove_backend);
}

amxb_be_unregister()

int amxb_be_unregister

(

amxb_be_funcs_t *const

funcs

)

Unregisters a backend interface.

A backend can call this function to remove the function table (backend interface) in a destructor function.

However this is not recommended. The backend will be unloaded from memory when it is not required anymore using the function amxb_be_remove or amxb_be_remove_all.

When a backend's function table is unregistered all open connections for that backend will be closed before the function table is removed.

Parameters

funcs

The back-end function table

Returns

returns 0 when the function table is removed.

Definition at line 406 of file amxb_backend_mngr.c.

                                                     {
    int retval = -1;
    amxc_htable_it_t* hit = NULL;
 
    when_null(funcs, exit);
    when_null(funcs->name, exit);
    when_true(*(funcs->name) == 0, exit);
 
    hit = amxc_htable_get(&amxb_backends, funcs->name);
 
    when_null(hit, exit);
    when_true(hit != &funcs->it, exit);
 
    amxc_htable_it_clean(hit, amxb_be_remove_backend);
 
    funcs->handle = NULL;
 
    retval = 0;
 
exit:
    if(amxc_htable_is_empty(&amxb_backends)) {
        amxc_htable_clean(&amxb_backends, NULL);
    }
    return retval;
}

amxb_be_who_has()

amxb_bus_ctx_t* amxb_be_who_has

(

const char *

object_path

)

Searches a bus context that can provide a certain object.

Invoke a describe on all open connections (bus contexts), the first bus context that can provide the object is returned.

If a bus context is found, it is stored in a lookup cache. When this method is called again with same object path, the bus context is retrieved from the cache.

The lookup cache is limited in size (default 5 entries), but can be changed by calling amxb_be_cache_set_size.

Parameters

object_path

an object path

Returns

NULL when no bus context can provide the object. A bus context otherwise.

Definition at line 650 of file amxb_backend_mngr.c.

                                                         {
    return amxb_be_who_has_impl(object_path, false);
}

amxb_check_be_versions()

int amxb_check_be_versions	(	const amxb_version_t *	min,
		const amxb_version_t *	max
	)

Checks if the library version is in the given range.

Parameters

min	the minimum version
max	the maximum version

Returns

• 0 when lib version is in the range
• 1 when lib version is not in the range

Definition at line 339 of file amxb_backend_mngr.c.

                                                      {
    if((min->major == -1) || (max->major == -1)) {
        return -1;
    }
 
    if(min->major > max->major) {
        return -1;
    }
    if(min->major == max->major) {
        if((min->minor > max->minor) && (max->minor != -1)) {
            return -1;
        }
        if(min->minor == max->minor) {
            if((min->build > max->build) && (max->build != -1)) {
                return -1;
            }
        }
    }
 
    return 0;
}

amxb_check_version()

int amxb_check_version

(

const amxb_version_t *

be_version

)

Compares the given version with the library version.

Parameters

be_version

the version that must be compared with the library version

Returns

• 0 when lib version and the given version are equal
• 1 when lib version is > than be version
• -1 when lib version is < than be version

Definition at line 311 of file amxb_backend_mngr.c.

                                                         {
    if(lib_version.major > be_version->major) {
        return 1;
    }
    if(lib_version.major < be_version->major) {
        return -1;
    }
    if(be_version->minor == -1) {
        return 0;
    }
    if(lib_version.minor > be_version->minor) {
        return 1;
    }
    if(lib_version.minor < be_version->minor) {
        return -1;
    }
    if(be_version->build == -1) {
        return 0;
    }
    if(lib_version.build > be_version->build) {
        return 1;
    }
    if(lib_version.build < be_version->build) {
        return -1;
    }
    return 0;
}

amxb_get_version()

const amxb_version_t* amxb_get_version

(

void

)

Gets the version of the library.

Returns

Returns a amxb_version_t struct containing the version of this library.

Definition at line 362 of file amxb_backend_mngr.c.

                                             {
    static amxb_version_t libv;
 
    libv.major = lib_version.major;
    libv.minor = lib_version.minor;
    libv.build = lib_version.build;
 
    return &libv;
}

amxb_set_config()

int amxb_set_config

(

amxc_var_t *const

configuration

)

Passes configuration options to the backends.

The configuration must be a variant containing a hash table. If in the hash table a key is found with the name of a loaded backend, the value of that key is passed to the backend. The value itself can also be a hash table.

When passing a NULL pointer the configuration is reset for all backends

Parameters

configuration

a hash table variant with configuration options

Returns

returns 0 when the configuration was set.

Definition at line 707 of file amxb_backend_mngr.c.

                                              {
    amxb_conf = config;
    if(config == NULL) {
        amxc_htable_for_each(hit, &amxb_backends) {
            amxb_be_funcs_t* funcs = amxc_htable_it_get_data(hit, amxb_be_funcs_t, it);
            amxb_apply_be_config(funcs, NULL);
        }
    } else {
        amxc_htable_for_each(hit, &amxb_backends) {
            amxb_be_funcs_t* funcs = amxc_htable_it_get_data(hit, amxb_be_funcs_t, it);
            amxc_var_t* be_config = GET_ARG(config, amxc_htable_it_get_key(hit));
            if(be_config == NULL) {
                be_config = amxc_var_add_key(amxc_htable_t, config, amxc_htable_it_get_key(hit), NULL);
            }
            amxb_apply_be_config(funcs, be_config);
        }
    }
 
    return 0;
}