Whole document tree
    

Whole document tree

bonobo-async

bonobo-async

Name

bonobo-async -- Helpers for invoking CORBA methods asynchronously

Synopsis



enum        BonoboAsyncArgFlag;
typedef     BonoboAsyncArg;
typedef     BonoboAsyncMethod;
struct      BonoboAsyncReply;
void        (*BonoboAsyncCallback)          (BonoboAsyncReply *reply,
                                             CORBA_Environment *ev,
                                             gpointer user_data);
void        bonobo_async_demarshal          (BonoboAsyncReply *reply,
                                             gpointer retval,
                                             gpointer *out_args);
void        bonobo_async_invoke             (const BonoboAsyncMethod *method,
                                             BonoboAsyncCallback cb,
                                             gpointer user_data,
                                             guint timeout_msec,
                                             CORBA_Object object,
                                             gpointer *args,
                                             CORBA_Environment *ev);
GIOPRecvBuffer* bonobo_async_handle_get_recv
                                            (BonoboAsyncReply *reply);

Description

The bonobo-async interface duplicates much of the equivalent CORBA asynchronous invocation functionality, in a non-standard way. This is regrettable, but appeared neccessary at the time for various reasons. This interface will be short lived, disappearing in the next versions of Bonobo.

The bonobo-async code uses fully type driven marshaling, so before you can invoke a method you need to fully describe the method you wish to invoke by constructing its type data. You probably really don't want to do this, however here is some example code to demonstrate how it can be done:

Example 1. A chunk of the asynchronous moniker code

typedef struct {
	Bonobo_Moniker       moniker;
	BonoboMonikerAsyncFn cb;
	gpointer             user_data;
} resolve_async_ctx_t;

static void
resolve_async_cb (BonoboAsyncReply  *handle,
		  CORBA_Environment *ev,
		  gpointer           user_data)
{
	resolve_async_ctx_t *ctx = user_data;

	if (BONOBO_EX (ev))
		ctx->cb (CORBA_OBJECT_NIL, ev, ctx->user_data);
	else {
		Bonobo_Unknown object;
		bonobo_async_demarshal (handle, &object, NULL);
		ctx->cb (object, ev, ctx->user_data);
	}

	bonobo_object_release_unref (ctx->moniker, ev);
	g_free (ctx);
}

void
bonobo_moniker_resolve_async (Bonobo_Moniker         moniker,
			      Bonobo_ResolveOptions *options,
			      const char            *interface_name,
			      CORBA_Environment     *ev,
			      guint                  timeout_msec,
			      BonoboMonikerAsyncFn   cb,
			      gpointer               user_data)
{
	/*
	 * A chunk of data describing the 'resolve' method.
	 */
	static const BonoboAsyncArg arguments [] = {
		{ TC_Bonobo_ResolveOptions, BONOBO_ASYNC_IN },
		{ TC_string,                BONOBO_ASYNC_IN },
		{ NULL }
	};
	static const CORBA_TypeCode exceptions [] = {
		TC_Bonobo_Moniker_InterfaceNotFound,
		TC_Bonobo_Moniker_UnknownPrefix,
		NULL
	};
	static const BonoboAsyncMethod method = {
		"resolve", 
		TC_Object, 
		arguments,
		exceptions
	};
	gpointer arg_values [2] = { &options, &interface_name };
	resolve_async_ctx_t *ctx;
	
	g_return_if_fail (ev != NULL);
	g_return_if_fail (cb != NULL);
	g_return_if_fail (moniker != CORBA_OBJECT_NIL);
	g_return_if_fail (options != CORBA_OBJECT_NIL);
	g_return_if_fail (interface_name != CORBA_OBJECT_NIL);

	ctx = g_new0 (resolve_async_ctx_t, 1);
	ctx->cb = cb;
	ctx->user_data = user_data;
	ctx->moniker = bonobo_object_dup_ref (moniker, ev);

	bonobo_async_invoke (&method, resolve_async_cb, ctx,
			     timeout_msec, ctx->moniker, arg_values, ev);
}
    

Details

enum BonoboAsyncArgFlag

typedef enum {
	BONOBO_ASYNC_IN  = 0x1,
	BONOBO_ASYNC_OUT = 0x2
} BonoboAsyncArgFlag;

An enumeration flagging the direction of an argument.

BONOBO_ASYNC_INFlags an argument as being In
BONOBO_ASYNC_OUTFlags an argument as being Out


BonoboAsyncArg

typedef struct {
	const CORBA_TypeCode  type;
	BonoboAsyncArgFlag    flag;
} BonoboAsyncArg;

A type describing a single CORBA method argument


BonoboAsyncMethod

typedef struct {
	const char           *name;
	const CORBA_TypeCode  ret_type;
	const BonoboAsyncArg *arguments;  /* NULL-terminated */
	const CORBA_TypeCode *exceptions; /* NULL-terminated */
} BonoboAsyncMethod;

A type describing a CORBA method


struct BonoboAsyncReply

struct BonoboAsyncReply;

An opaque async reply handle


BonoboAsyncCallback ()

void        (*BonoboAsyncCallback)          (BonoboAsyncReply *reply,
                                             CORBA_Environment *ev,
                                             gpointer user_data);

This callback is invoked either when the invocation times out, in which case an ex_CORBA_COMM_FAILURE system exception will be passed in ev. Or with a valid reply, in which case arguments should be de-marshaled using bonobo_async_demarshal.

reply :the reply handle
ev :the CORBA_Environment
user_data :the callback's associated user data.


bonobo_async_demarshal ()

void        bonobo_async_demarshal          (BonoboAsyncReply *reply,
                                             gpointer retval,
                                             gpointer *out_args);

When a user's async callback happens ( when a method's return data arrives back ) this function is typicaly used by the callback to de-marshal the arguments associated with the method, such as the retval, and an array of pointers to memory in which to store the returned InOut / Out arguments in order.

reply : 
retval : pointer to variable to store retval in
out_args : array of pointers to vars for InOut / Out params.


bonobo_async_invoke ()

void        bonobo_async_invoke             (const BonoboAsyncMethod *method,
                                             BonoboAsyncCallback cb,
                                             gpointer user_data,
                                             guint timeout_msec,
                                             CORBA_Object object,
                                             gpointer *args,
                                             CORBA_Environment *ev);

Given a type based description of a CORBA method the method is invoked asynchronously. If an error occurs in invocation an exception is fired in ev and cb will never be invoked. Otherwise, cb is invoked, either on the timeout - in which case an ex_CORBA_COMM_FAILURE system exception will be returned, or when the method returns with whatever data / exceptions are relevant.

method : method description
cb : async callback
user_data : associated callback user data
timeout_msec : timeout in milli-seconds
object : object to invoke method on
args : array of ordered In/InOut arguments in same order as in method
ev : CORBA exception environment


bonobo_async_handle_get_recv ()

GIOPRecvBuffer* bonobo_async_handle_get_recv
                                            (BonoboAsyncReply *reply);

This method can be used to extract the internal GIOP buffer on the reply, for advanced custom de-marshaling.

reply : 
Returns : the internal reply buffer.

bonobo-async

bonobo-async

Name

bonobo-async -- Helpers for invoking CORBA methods asynchronously

Synopsis



enum        BonoboAsyncArgFlag;
typedef     BonoboAsyncArg;
typedef     BonoboAsyncMethod;
struct      BonoboAsyncReply;
void        (*BonoboAsyncCallback)          (BonoboAsyncReply *reply,
                                             CORBA_Environment *ev,
                                             gpointer user_data);
void        bonobo_async_demarshal          (BonoboAsyncReply *reply,
                                             gpointer retval,
                                             gpointer *out_args);
void        bonobo_async_invoke             (const BonoboAsyncMethod *method,
                                             BonoboAsyncCallback cb,
                                             gpointer user_data,
                                             guint timeout_msec,
                                             CORBA_Object object,
                                             gpointer *args,
                                             CORBA_Environment *ev);
GIOPRecvBuffer* bonobo_async_handle_get_recv
                                            (BonoboAsyncReply *reply);

Description

The bonobo-async interface duplicates much of the equivalent CORBA asynchronous invocation functionality, in a non-standard way. This is regrettable, but appeared neccessary at the time for various reasons. This interface will be short lived, disappearing in the next versions of Bonobo.

The bonobo-async code uses fully type driven marshaling, so before you can invoke a method you need to fully describe the method you wish to invoke by constructing its type data. You probably really don't want to do this, however here is some example code to demonstrate how it can be done:

Example 1. A chunk of the asynchronous moniker code

typedef struct {
	Bonobo_Moniker       moniker;
	BonoboMonikerAsyncFn cb;
	gpointer             user_data;
} resolve_async_ctx_t;

static void
resolve_async_cb (BonoboAsyncReply  *handle,
		  CORBA_Environment *ev,
		  gpointer           user_data)
{
	resolve_async_ctx_t *ctx = user_data;

	if (BONOBO_EX (ev))
		ctx->cb (CORBA_OBJECT_NIL, ev, ctx->user_data);
	else {
		Bonobo_Unknown object;
		bonobo_async_demarshal (handle, &object, NULL);
		ctx->cb (object, ev, ctx->user_data);
	}

	bonobo_object_release_unref (ctx->moniker, ev);
	g_free (ctx);
}

void
bonobo_moniker_resolve_async (Bonobo_Moniker         moniker,
			      Bonobo_ResolveOptions *options,
			      const char            *interface_name,
			      CORBA_Environment     *ev,
			      guint                  timeout_msec,
			      BonoboMonikerAsyncFn   cb,
			      gpointer               user_data)
{
	/*
	 * A chunk of data describing the 'resolve' method.
	 */
	static const BonoboAsyncArg arguments [] = {
		{ TC_Bonobo_ResolveOptions, BONOBO_ASYNC_IN },
		{ TC_string,                BONOBO_ASYNC_IN },
		{ NULL }
	};
	static const CORBA_TypeCode exceptions [] = {
		TC_Bonobo_Moniker_InterfaceNotFound,
		TC_Bonobo_Moniker_UnknownPrefix,
		NULL
	};
	static const BonoboAsyncMethod method = {
		"resolve", 
		TC_Object, 
		arguments,
		exceptions
	};
	gpointer arg_values [2] = { &options, &interface_name };
	resolve_async_ctx_t *ctx;
	
	g_return_if_fail (ev != NULL);
	g_return_if_fail (cb != NULL);
	g_return_if_fail (moniker != CORBA_OBJECT_NIL);
	g_return_if_fail (options != CORBA_OBJECT_NIL);
	g_return_if_fail (interface_name != CORBA_OBJECT_NIL);

	ctx = g_new0 (resolve_async_ctx_t, 1);
	ctx->cb = cb;
	ctx->user_data = user_data;
	ctx->moniker = bonobo_object_dup_ref (moniker, ev);

	bonobo_async_invoke (&method, resolve_async_cb, ctx,
			     timeout_msec, ctx->moniker, arg_values, ev);
}
    

Details

enum BonoboAsyncArgFlag

typedef enum {
	BONOBO_ASYNC_IN  = 0x1,
	BONOBO_ASYNC_OUT = 0x2
} BonoboAsyncArgFlag;

An enumeration flagging the direction of an argument.

BONOBO_ASYNC_INFlags an argument as being In
BONOBO_ASYNC_OUTFlags an argument as being Out


BonoboAsyncArg

typedef struct {
	const CORBA_TypeCode  type;
	BonoboAsyncArgFlag    flag;
} BonoboAsyncArg;

A type describing a single CORBA method argument


BonoboAsyncMethod

typedef struct {
	const char           *name;
	const CORBA_TypeCode  ret_type;
	const BonoboAsyncArg *arguments;  /* NULL-terminated */
	const CORBA_TypeCode *exceptions; /* NULL-terminated */
} BonoboAsyncMethod;

A type describing a CORBA method


struct BonoboAsyncReply

struct BonoboAsyncReply;

An opaque async reply handle


BonoboAsyncCallback ()

void        (*BonoboAsyncCallback)          (BonoboAsyncReply *reply,
                                             CORBA_Environment *ev,
                                             gpointer user_data);

This callback is invoked either when the invocation times out, in which case an ex_CORBA_COMM_FAILURE system exception will be passed in ev. Or with a valid reply, in which case arguments should be de-marshaled using bonobo_async_demarshal.

reply :the reply handle
ev :the CORBA_Environment
user_data :the callback's associated user data.


bonobo_async_demarshal ()

void        bonobo_async_demarshal          (BonoboAsyncReply *reply,
                                             gpointer retval,
                                             gpointer *out_args);

When a user's async callback happens ( when a method's return data arrives back ) this function is typicaly used by the callback to de-marshal the arguments associated with the method, such as the retval, and an array of pointers to memory in which to store the returned InOut / Out arguments in order.

reply : 
retval : pointer to variable to store retval in
out_args : array of pointers to vars for InOut / Out params.


bonobo_async_invoke ()

void        bonobo_async_invoke             (const BonoboAsyncMethod *method,
                                             BonoboAsyncCallback cb,
                                             gpointer user_data,
                                             guint timeout_msec,
                                             CORBA_Object object,
                                             gpointer *args,
                                             CORBA_Environment *ev);

Given a type based description of a CORBA method the method is invoked asynchronously. If an error occurs in invocation an exception is fired in ev and cb will never be invoked. Otherwise, cb is invoked, either on the timeout - in which case an ex_CORBA_COMM_FAILURE system exception will be returned, or when the method returns with whatever data / exceptions are relevant.

method : method description
cb : async callback
user_data : associated callback user data
timeout_msec : timeout in milli-seconds
object : object to invoke method on
args : array of ordered In/InOut arguments in same order as in method
ev : CORBA exception environment


bonobo_async_handle_get_recv ()

GIOPRecvBuffer* bonobo_async_handle_get_recv
                                            (BonoboAsyncReply *reply);

This method can be used to extract the internal GIOP buffer on the reply, for advanced custom de-marshaling.

reply : 
Returns : the internal reply buffer.