Remote Function Invoke

Data Structures
struct	_amxb_request
	A request structure. More...

Functions
int	amxb_new_invoke (amxb_invoke_t **invoke_ctx, amxb_bus_ctx_t *const ctx, const char *object, const char *interface, const char *method)
	Prepares a remote function invocation. More...
void	amxb_free_invoke (amxb_invoke_t **invoke_ctx)
	Deletes a function invoke context, and frees allocated memory. More...
int	amxb_invoke (amxb_invoke_t *invoke_ctx, amxc_var_t *args, amxc_var_t *ret, amxb_be_cb_fn_t fn, void *priv, int timeout)
	Invokes a remote function, as defined by the function invoke context. More...
int	amxb_async_invoke (amxb_invoke_t *invoke_ctx, amxc_var_t *args, amxb_be_cb_fn_t fn, amxb_be_done_cb_fn_t done_fn, void *priv, amxb_request_t **req)
	Invokes a remote function, as defined by the function invoke context. More...
int	amxb_wait_for_request (amxb_request_t *req, int timeout)
	Waits for an asynchronous remote function invoke to finish. More...
int	amxb_request_new (amxb_request_t **request)
	Allocates an empty amxb_request_t. More...
amxb_bus_ctx_t *	amxb_request_get_ctx (amxb_request_t *request)
	Get the bus context of the request if any. More...
int	amxb_close_request (amxb_request_t **req)
	Closes a previously create remote function called context. More...

Detailed Description

Function Documentation

amxb_async_invoke()

int amxb_async_invoke	(	amxb_invoke_t *	invoke_ctx,
		amxc_var_t *	args,
		amxb_be_cb_fn_t	fn,
		amxb_be_done_cb_fn_t	done_fn,
		void *	priv,
		amxb_request_t **	req
	)

Invokes a remote function, as defined by the function invoke context.

Before invoking a function, an function invoke context must be created using amxb_new_invoke.

This method returns immediately, without waiting for the result (asynchronous I/O), to be able to receive the result of remote function call it is recommended that you use an eventloop.

The arguments passed must be in a amxc variant of type AMXC_VAR_ID_HTABLE. The order of the arguments is not important.

A callback function can be given, which is called for each individual return value. The private data will be passed to the callback function. If no callback function is given, the return values can be fetched from the request context, see _amxb_request

A done callback function can be given, which is called when the remote function call is finished. The private data will be passed to the done callback function. It is recommended to provide a done function, unless you are not interested when the remote function is done.

Note

This function allocates memory to store the request information. When the request is not needed anymore it must be freed using amxb_close_request.

Warning

When the connection represented by the bus context (amxb_bus_ctx) is closed, the allocated request is removed and can not be used anymore.

Parameters

invoke_ctx	The function invoke context as created with amxb_new_invoke
args	the function arguments in a amxc variant htable type
fn	a callback function
done_fn	a done callback function
priv	private data that will be passed to the callback function (optional, can be NULL)
req	the request context.

Returns

• AMXB_STATUS_OK remote function is started
• AMXB_ERROR_NOT_SUPPORTED_OP the backend does not support remote asynchronous function calls
• AMXB_ERROR_UNKNOWN when invalid arguments are passed
• Or any bus related error. See AMXB_ERROR_BUS_XXXX

Definition at line 396 of file amxb_ba_invoke.c.

                                                {
    int retval = -1;
    amxb_bus_ctx_t* ctx = NULL;
    amxb_req_t* req = NULL;
 
    when_null(invoke_ctx, exit);
    when_null(invoke_ctx->it.llist, exit);
    when_null(request, exit);
    ctx = amxc_container_of(invoke_ctx->it.llist, amxb_bus_ctx_t, invoke_ctxs);
 
    req = (amxb_req_t*) calloc(1, sizeof(amxb_req_t));
    when_null(req, exit);
    *request = &req->data;
 
    amxc_var_new(&req->data.result);
    req->data.cb_fn = fn;
    req->data.done_fn = done_fn;
    req->data.priv = priv;
 
    if(amxb_is_local_object(ctx, invoke_ctx->object)) {
        req->local = true;
        retval = amxb_invoke_local_impl(invoke_ctx, ctx, args, *request, true);
    } else {
        req->local = false;
        retval = amxb_invoke_be_impl(invoke_ctx, ctx, args, *request, 0, true);
    }
 
    if(retval == 0) {
        amxc_llist_append(&ctx->requests, &req->it);
    }
 
exit:
    if((retval != 0) && (req != NULL)) {
        amxc_var_delete(&req->data.result);
        free(req);
        *request = NULL;
    }
 
    return retval;
}

amxb_close_request()

int amxb_close_request

(

amxb_request_t **

req

)

Closes a previously create remote function called context.

Deletes and frees the request context created with amxb_async_invoke.

When the context is deleted, none of the callback functions will be called, not event when the remote function call was not yet finished.

Parameters

req	The remote function invoke request

Returns

• AMXB_STATUS_OK when remote function is finished
• AMXB_ERROR_UNKNOWN when invalid arguments are passed

Definition at line 498 of file amxb_ba_invoke.c.

                                                 {
    int retval = -1;
    const amxb_bus_ctx_t* ctx = NULL;
    const amxb_be_funcs_t* fns = NULL;
    amxb_req_t* req = NULL;
 
    when_null(request, exit);
    when_null((*request), exit);
 
    req = amxc_container_of(*request, amxb_req_t, data);
    amxc_var_delete(&(*request)->result);
 
    if(req->in_flight || req->wait) {
        req->closed = true;
        *request = NULL;
        retval = 0;
        goto exit;
    }
 
    retval = 0;
    when_false(amxc_llist_it_is_in_list(&req->it), exit_free);
 
    ctx = amxc_container_of(req->it.llist, amxb_bus_ctx_t, requests);
    fns = ctx->bus_fn;
 
    if(amxb_is_valid_be_func(fns, close_request, fns->close_request)) {
        retval = fns->close_request(ctx->bus_ctx, *request);
    } else {
        retval = AMXB_ERROR_NOT_SUPPORTED_OP;
    }
 
    amxc_llist_it_take(&req->it);
 
exit_free:
    free(req);
    *request = NULL;
exit:
    return retval;
}

amxb_free_invoke()

void amxb_free_invoke

(

amxb_invoke_t **

invoke_ctx

)

Deletes a function invoke context, and frees allocated memory.

Frees the allocated memory for the function invoke context.

Parameters

invoke_ctx

The function invoke context, is reset to NULL

Definition at line 324 of file amxb_ba_invoke.c.

                                                  {
    const amxb_be_funcs_t* fns = NULL;
    amxb_bus_ctx_t* ctx = NULL;
 
    when_null(invoke_ctx, exit);
    when_null(*invoke_ctx, exit);
 
    if(amxc_llist_it_is_in_list(&(*invoke_ctx)->it)) {
        ctx = amxc_container_of((*invoke_ctx)->it.llist,
                                amxb_bus_ctx_t, invoke_ctxs);
        fns = ctx->bus_fn;
        if(amxb_is_valid_be_func(fns, free_invoke, fns->free_invoke)) {
            fns->free_invoke(*invoke_ctx);
        }
    }
 
    amxc_llist_it_take(&(*invoke_ctx)->it);
    free((*invoke_ctx)->object);
    free((*invoke_ctx)->interface);
    free((*invoke_ctx)->method);
    free((*invoke_ctx));
 
    *invoke_ctx = NULL;
 
exit:
    return;
}

amxb_invoke()

int amxb_invoke	(	amxb_invoke_t *	invoke_ctx,
		amxc_var_t *	args,
		amxc_var_t *	ret,
		amxb_be_cb_fn_t	fn,
		void *	priv,
		int	timeout
	)

Invokes a remote function, as defined by the function invoke context.

Before invoking a function, an function invoke context must be created using amxb_new_invoke.

This method is blocking, it will return when the remote function call is done or when it has failed.

The arguments passed must be in a amxc variant of type AMXC_VAR_ID_HTABLE. The order of the arguments is not important.

The return value must be an initialized amxc variant, the type must not be set.

Optionally a callback function can be given, which is called for each individual return value. The private data will be passed to the callback function.

As this function is blocking, a time out in seconds, must be provided. If the remote function call is not done in the given timeout, the function call (on the client side) is aborted.

Parameters

invoke_ctx	The function invoke context as created with amxb_new_invoke
args	the function arguments in a amxc variant htable type
ret	when the remote function call is done, it will contain an array of return values.
fn	a callback function (optional, can be NULL).
priv	private data that will be passed to the callback function (optional, can be NULL)
timeout	in seconds

Returns

• AMXB_STATUS_OK remote function call done and all ok
• AMXB_ERROR_NOT_SUPPORTED_OP the backend does not support remote function calls
• AMXB_ERROR_UNKNOWN when invalid arguments are passed
• Or any bus related error. See AMXB_ERROR_BUS_XXXX

Definition at line 352 of file amxb_ba_invoke.c.

                             {
    int retval = -1;
    amxb_bus_ctx_t* ctx = NULL;
    amxc_var_t temp_var;
    amxb_req_t* req = NULL;
    amxb_request_t* request = NULL;
 
    amxc_var_init(&temp_var);
 
    when_null(invoke_ctx, exit);
    when_null(invoke_ctx->it.llist, exit);
 
    ctx = amxc_container_of(invoke_ctx->it.llist, amxb_bus_ctx_t, invoke_ctxs);
    req = (amxb_req_t*) calloc(1, sizeof(amxb_req_t));
    when_null(req, exit);
    request = &req->data;
 
    request->result = (ret == NULL) ? &temp_var : ret;
    request->cb_fn = fn;
    request->done_fn = NULL;
    request->bus_retval = 0;
    request->bus_data = NULL;
    request->priv = priv;
 
    if(amxb_is_local_object(ctx, invoke_ctx->object)) {
        retval = amxb_invoke_local_impl(invoke_ctx, ctx, args, request, false);
        if(retval == amxd_status_deferred) {
            retval = amxb_invoke_wait_local(req, timeout);
        }
    } else {
        retval = amxb_invoke_be_impl(invoke_ctx, ctx, args, request, timeout, false);
    }
    free(req);
 
exit:
    amxc_var_clean(&temp_var);
    return retval;
}

amxb_new_invoke()

int amxb_new_invoke	(	amxb_invoke_t **	invoke_ctx,
		amxb_bus_ctx_t *const	ctx,
		const char *	object,
		const char *	interface,
		const char *	method
	)

Prepares a remote function invocation.

Allocates a remote function invoke context. Depending on the bus specific backend used, this function prepares the remote function invoke.

The created function invoke context can be re-used many times to call the same function.

Note

This function allocates memory for the function invoke context. The context can be freed using amxb_free_invoke

Warning

When the connection represented by the bus context (amxb_bus_ctx) is closed, the allocated invoke_ctx is removed and can not be used anymore.

Parameters

invoke_ctx	The place where the function invoke context is stored
ctx	the bus connection context
object	the path to the object (mandatory)
interface	the interface name, that contains the function (optional) when not used provide a NULL pointer
method	the name of the function that is going to be called (mandatory)

Returns

• AMXB_STATUS_OK when function invoke context is created
• AMXB_ERROR_UNKNOWN when invalid arguments are passed or when failed to allocate memory

Definition at line 281 of file amxb_ba_invoke.c.

                                        {
    int retval = amxd_status_unknown_error;
    const amxb_be_funcs_t* fns = NULL;
 
    when_null(invoke_ctx, exit);
    when_not_null(*invoke_ctx, exit);
    when_null(ctx, exit);
    when_null(ctx->bus_ctx, exit);
    when_str_empty(method, exit);
 
    *invoke_ctx = (amxb_invoke_t*) calloc(1, sizeof(amxb_invoke_t));
    when_null((*invoke_ctx), exit);
 
    (*invoke_ctx)->object = object == NULL ? strdup("") : strdup(object);
    when_null((*invoke_ctx)->object, exit);
    (*invoke_ctx)->interface = interface == NULL ? NULL : strdup(interface);
    (*invoke_ctx)->method = strdup(method);
    when_null((*invoke_ctx)->method, exit);
 
    amxb_trim((*invoke_ctx)->object, isdot);
    amxb_trim((*invoke_ctx)->method, isbrace);
 
    fns = ctx->bus_fn;
    if(amxb_is_valid_be_func(fns, new_invoke, fns->new_invoke)) {
        retval = fns->new_invoke(*invoke_ctx);
    } else {
        retval = 0;
    }
 
    if(retval == 0) {
        amxc_llist_append(&ctx->invoke_ctxs, &(*invoke_ctx)->it);
    } else {
        amxb_free_invoke(invoke_ctx);
    }
 
exit:
    return retval;
}

amxb_request_get_ctx()

amxb_bus_ctx_t* amxb_request_get_ctx

(

amxb_request_t *

request

)

Get the bus context of the request if any.

Returns the bus context for which the request was created.

Parameters

request

the request pointer

Returns

returns the bus context, NULL if the request is not associated with a bus context.

Definition at line 484 of file amxb_ba_invoke.c.

                                                              {
    amxb_req_t* req = NULL;
    amxb_bus_ctx_t* ctx = NULL;
 
    when_null(request, exit);
    req = amxc_container_of(request, amxb_req_t, data);
    if(amxc_llist_it_is_in_list(&req->it)) {
        ctx = amxc_container_of(req->it.llist, amxb_bus_ctx_t, requests);
    }
 
exit:
    return ctx;
}

amxb_request_new()

int amxb_request_new

(

amxb_request_t **

request

)

Allocates an empty amxb_request_t.

Allocates and initializes an empty amxb_request_t.

This function is mainly intended for use in back-end implementations. Client applications should use amxb_async_invoke to allocate and initialize such a structure.

Parameters

request

the request pointer to initialize

Returns

• AMXB_STATUS_OK when remote function is finished
• AMXB_ERROR_UNKNOWN when invalid arguments are passed

Definition at line 470 of file amxb_ba_invoke.c.

                                               {
    amxb_req_t* req = NULL;
    int retval = AMXB_ERROR_UNKNOWN;
 
    req = (amxb_req_t*) calloc(1, sizeof(amxb_req_t));
    when_null(req, exit);
 
    *request = &req->data;
    retval = AMXB_STATUS_OK;
 
exit:
    return retval;
}

amxb_wait_for_request()

int amxb_wait_for_request	(	amxb_request_t *	req,
		int	timeout
	)

Waits for an asynchronous remote function invoke to finish.

Waits until a remote function invoke, created with amxb_async_invoke is finished.

When a done callback was provided, the done callback will be called before this function returns, unless a timeout occurs.

Parameters

req	The remote function invoke request
timeout	in seconds

Returns

• AMXB_STATUS_OK when remote function is finished
• AMXB_ERROR_UNKNOWN when invalid arguments are passed

Definition at line 442 of file amxb_ba_invoke.c.

                                                                {
    int retval = -1;
    amxb_req_t* req = NULL;
    const amxb_be_funcs_t* fns = NULL;
    const amxb_bus_ctx_t* ctx = NULL;
 
    when_null(request, exit);
    req = amxc_container_of(request, amxb_req_t, data);
 
    if(req->local) {
        retval = amxb_invoke_wait_local(req, timeout);
        goto exit;
    }
 
    ctx = amxb_request_get_ctx(request);
    when_null(ctx, exit);
    fns = ctx->bus_fn;
 
    if(amxb_is_valid_be_func(fns, wait_request, fns->wait_request)) {
        retval = fns->wait_request(ctx->bus_ctx, request, timeout);
    } else {
        retval = AMXB_ERROR_NOT_SUPPORTED_OP;
    }
 
exit:
    return retval;
}