Typedefs
typedef int	EVstone

typedef int	EVaction

typedef struct _EVSource *	EVsource

typedef void(*	EVSubmitCallbackFunc )(CManager cm, EVstone target, void *client_data)

typedef int(*	EVSimpleHandlerFunc )(CManager cm, void message, void client_data, attr_list attrs)

typedef int(*	EVRawHandlerFunc )(CManager cm, void message, int msg_len, void client_data, attr_list attrs)

typedef void(*	EVStoneCloseHandlerFunc )(CManager cm, CMConnection conn, int stone, void *client_data)

typedef void(*	EVFreeFunction )(void event_data, void client_data)

typedef int(*	EVImmediateHandlerFunc )(CManager cm, struct _event_item event, void client_data, attr_list attrs, int out_count, int *out_stones)

typedef attr_list(*	CMperf_upcall )(CManager cm, void *buffer, long length, int type, attr_list list)

Functions
EVstone	EValloc_stone (CManager cm)

void	EVfree_stone (CManager cm, EVstone stone)

EVaction	EVassoc_terminal_action (CManager cm, EVstone stone, FMStructDescList format_list, EVSimpleHandlerFunc handler, void *client_data)

EVaction	EVassoc_raw_terminal_action (CManager cm, EVstone stone, EVRawHandlerFunc handler, void *client_data)

EVstone	EVcreate_terminal_action (CManager cm, FMStructDescList format_list, EVSimpleHandlerFunc handler, void *client_data)

EVaction	EVassoc_multi_action (CManager cm, EVstone stone, char action_spec, void client_data)

EVaction	EVassoc_immediate_action (CManager cm, EVstone stone, char action_spec, void client_data)

EVstone	EVcreate_immediate_action (CManager cm, char action_spec, EVstone target_list)

int	EVaction_set_output (CManager cm, EVstone stone, EVaction action, int output_index, EVstone target_stone)

int	EVstone_set_output (CManager cm, EVstone stone, int output_index, EVstone target_stone)

EVaction	EVassoc_filter_action (CManager cm, EVstone stone, FMStructDescList incoming_format_list, EVSimpleHandlerFunc handler, EVstone out_stone, void *client_data)

EVaction	EVassoc_bridge_action (CManager cm, EVstone stone, attr_list contact_list, EVstone remote_stone)

EVstone	EVcreate_bridge_action (CManager cm, attr_list contact_list, EVstone remote_stone)

EVaction	EVassoc_thread_bridge_action (CManager cm, EVstone stone, CManager target_cm, EVstone target_stone)

EVstone	EVcreate_thread_bridge_action (CManager cm, CManager target_cm, EVstone target_stone)

EVaction	EVassoc_split_action (CManager cm, EVstone stone, EVstone *target_list)

EVstone	EVcreate_split_action (CManager cm, EVstone *target_list)

int	EVaction_add_split_target (CManager cm, EVstone stone, EVaction action, EVstone target_stone)

void	EVaction_remove_split_target (CManager cm, EVstone stone, EVaction action, EVstone target_stone)

void	EVstone_add_split_target (CManager cm, EVstone stone, EVstone target_stone)

void	EVstone_remove_split_target (CManager cm, EVstone stone, EVstone target_stone)

EVaction	EVassoc_congestion_action (CManager cm, EVstone stone, char action_spec, void client_data)

EVstone	EVcreate_store_action (CManager cm, EVstone out_stone, int store_limit)

EVstone	EVcreate_stone_action (CManager cm, char *action_spec)

EVaction	EVassoc_store_action (CManager cm, EVstone stone_num, EVstone out_stone, int store_limit)

void	EVclear_stored (CManager cm, EVstone stone_num, EVaction action_num)

void	EVsend_stored (CManager cm, EVstone stone_num, EVaction action_num)

int	EVstore_count (CManager cm, EVstone stone_num, EVaction action_num)

int	EVstore_is_sending (CManager cm, EVstone stone_num, EVaction action_num)

void	EVstore_start_send (CManager cm, EVstone stone_num, EVaction action_num)

void	EVset_store_limit (CManager cm, EVstone stone_num, EVaction action_num, int store_limit)

EVsource	EVcreate_submit_handle (CManager cm, EVstone stone, FMStructDescList data_format)

void	EVfree_source (EVsource source)

EVsource	EVcreate_submit_handle_free (CManager cm, EVstone stone, FMStructDescList data_format, EVFreeFunction free_func, void *client_data)

void	EVsubmit (EVsource source, void *data, attr_list attrs)

void	EVsubmit_general (EVsource source, void *data, EVFreeFunction free_func, attr_list attrs)

void	EVsubmit_encoded (CManager cm, EVstone stone, void *data, int data_len, attr_list attrs)

int	EVtransfer_events (CManager cm, EVstone src_stone, EVstone dest_stone)

int	EVtake_event_buffer (CManager cm, void *event)

void	EVreturn_event_buffer (CManager cm, void *event)

FMFormat	EVget_src_ref_format (EVsource source)

void	EVenable_auto_stone (CManager cm, EVstone stone_num, int period_sec, int period_usec)

EVstone	EVcreate_auto_stone (CManager cm, int period_sec, int period_usec, char *action_spec, EVstone out_stone)

void	EVstall_stone (CManager cm, EVstone stone_id)

void	EVunstall_stone (CManager cm, EVstone stone_id)

int	EVsubmit_or_wait (EVsource source, void data, attr_list attrs, EVSubmitCallbackFunc cb, void user_data)

int	EVsubmit_encoded_or_wait (CManager cm, EVstone stone, void data, int data_len, attr_list attrs, EVSubmitCallbackFunc cb, void user_data)

int	EVfreeze_stone (CManager cm, EVstone stone_id)

int	EVunfreeze_stone (CManager cm, EVstone stone_id)

int	EVdrain_stone (CManager cm, EVstone stone_id)

EVstone	EVexecuting_stone (CManager cm)

EVevent_list	EVextract_stone_events (CManager cm, EVstone stone_id)

attr_list	EVextract_attr_list (CManager cm, EVstone stone_id)

void	EVset_attr_list (CManager cm, EVstone stone_id, attr_list list)

int	EVdestroy_stone (CManager cm, EVstone stone_id)

char *	create_filter_action_spec (FMStructDescList format_list, char *function)

char *	create_router_action_spec (FMStructDescList format_list, char *function)

char *	create_transform_action_spec (FMStructDescList format_list, FMStructDescList out_format_list, char *function)

char *	create_multityped_action_spec (FMStructDescList input_format_lists, char function)

void	EVadd_dll_search_dir (char *path_string)

void	EVadd_standard_structs (CManager cm, FMStructDescList *lists)

void	EVregister_close_handler (CManager cm, EVStoneCloseHandlerFunc handler, void *client_data)

void	EVdump_stone (CManager cm, EVstone stone_num)

void	EVassoc_conversion_action (CManager cm, int stone_id, int stage, FMFormat target_format, FMFormat incoming_format)

attr_list	CMtest_transport (CMConnection conn, attr_list how)

void	CMinstall_perf_upcall (CManager cm, CMperf_upcall upcall)

Detailed Description

Typedef Documentation

typedef int EVstone

EVStone a stone is an elementary building block of paths

EVStone is an integer-typed opaque handle. Its only external use is to act as an external stone identifier for remote operations (such as specifying the remote target stone in a bridge action)

typedef int EVaction

EVaction actions, associated with stones, are the mechanisms through which data flow operations are defined.

EVaction is an opaque integer-typed handle. An EVaction handle is interpreted in the context of the stone it is associated with and is not unique across stones.

typedef struct _EVSource* EVsource

EVsource an EVsource is a source handle used to submit events to EVpath. An EVsource specifies both the (local) target stone and the format (fully-specified structured data type) of the data that will be submitted using this handle.

EVsource is an opaque handle.

typedef void(* EVSubmitCallbackFunc)(CManager cm, EVstone target, void *client_data)

The prototype for a EV submit callback function.

Used by EVsubmit_or_wait()

Parameters

cm	The CManager with which this callback function was registered.
target	The target stone that can now submit without stalling.
client_data	This value is the same client_data value that was supplied in the call.

typedef int(* EVSimpleHandlerFunc)(CManager cm, void *message, void *client_data, attr_list attrs)

The prototype for an EVPath terminal handler function.

EVPath allows application-routines matching this prototype to be registered as sinks on stones.

Parameters

cm	The CManager with which this handler was registered.
message	A pointer to the incoming data, cast to void*. The real data is formatted to match the fields of with which the format was registered.
client_data	This value is the same client_data value that was supplied in the EVassoc_terminal_action() call. It is not interpreted by CM, but instead can be used to maintain some application context.
attrs	The attributes (set of name/value pairs) that this message was delivered with. These are determined by the transport and may include those specified in CMwrite_attr() when the data was written.

Examples:: dfg_client.c, dfg_client3.c, dfg_master.c, dfg_master2.c, dfg_master3.c, and dfg_master4.c.

typedef int(* EVRawHandlerFunc)(CManager cm, void *message, int msg_len, void *client_data, attr_list attrs)

The prototype for an EVPath raw terminal handler function.

EVPath allows application-routines matching this prototype to be registered as raw sinks (receiving encoded FFS data) on stones.

Parameters

cm	The CManager with which this handler was registered.
message	A pointer to the incoming data, cast to void*. The real data is formatted to match the fields of with which the format was registered.
msg_len	The length in bytes of the message block
client_data	This value is the same client_data value that was supplied in the EVassoc_terminal_action() call. It is not interpreted by CM, but instead can be used to maintain some application context.
attrs	The attributes (set of name/value pairs) that this message was delivered with. These are determined by the transport and may include those specified in CMwrite_attr() when the data was written.

typedef void(* EVStoneCloseHandlerFunc)(CManager cm, CMConnection conn, int stone, void *client_data)

The prototype for a EVPath bridge stone close handler.

Functions matching of this prototype can be registered with EVregister_close_handler().

Parameters

cm	The CManager with which this handler was registered.
conn	The CMConnection which is being closed.
the	stone ID of the bridge stone which has closed
client_data	This value is the same client_data value that was supplied in the EVregister_close_handler() call. It is not interpreted by CM, but instead can be used to maintain some application context.

typedef void(* EVFreeFunction)(void *event_data, void *client_data)

The prototype for a function which will free the memory associated with an event.

Normally, the EVpath event submission functions do not return until it is safe for the application to destroy the submitted data (I.E. until EVpath is finished with it). However, if a "free" function is associated with the event through the EVsource, EVpath will return sooner if there is another thread of control available to prosecute the actions on the event. EVpath will then call the application-supplied free function to free the event when the event data is no longer required. Application-supplied event free functions must satisfy this profile.

Parameters

event_data	The address of the event data, expressed as a void*.
client_data	The parameter is used to supply the free function with the same client_data value that was specified in the EVcreate_submit_handle_free() call.

typedef int(* EVImmediateHandlerFunc)(CManager cm, struct _event_item *event, void *client_data, attr_list attrs, int out_count, int *out_stones)

The prototype of a specific immediate handler function.

This function prototype is used by the EVPath internal "response" interface. At some point, the response interface will likely become external so that EVPath's response to unknown data can be customized. However, at the moment this is an internal interface.

typedef attr_list(* CMperf_upcall)(CManager cm, void *buffer, long length, int type, attr_list list)

Callback function to support transport tests

CMperf_upcall is the type of a callback function that is used as part of CM transport testing. This function is called on the receiving side of the transport for every message that arrives. The data of the message and it's length are provided in parameters 'buffer' and 'length' respectively. The 'type' parameter varies with the message that arrives. Current types are '0' for test initiation (I.E. the first short header of a bandwidth tests), '1' for "body" messages (I.E. the N-1 repeats of a bandwidth test), and '2' for the "final" message (I.E. the last message of a bandwidth test). The return value is only read for the final message, and it is returned to caller of CMtest_transport(), so should contain the final values of testing.

Function Documentation

EVstone EValloc_stone ( CManager cm )

Allocate a stone.

Stones are the basic abstraction of EVPath, the entity to which events are submitted and with which actions are associated. The value returned from EValloc_stone() is actually a simple integer which may be transmitted to remote locations (for example for use in remote bridge actions).

Parameters

cm	The CManager which will manage the control for this stone.

Returns: The stone identifier, an integer EVstone value, which can be used in subsequent calls to associate actions with the stone.

void EVfree_stone	(	CManager	cm,
		EVstone	stone
	)

Free a stone.

This call also free's all actions and data associated with a stone, including enqueued events if any.

Parameters

cm	The CManager from which this stone was allocated.
stone	The stone to free.

EVaction EVassoc_terminal_action	(	CManager	cm,
		EVstone	stone,
		FMStructDescList	format_list,
		EVSimpleHandlerFunc	handler,
		void *	client_data
	)

Associate a terminal action (sink) with a stone.

The specified handler will be called when data matching the format_list arrives at the stone. The event data supplied may not remain valid after the handler call returns. EVtake_event_buffer() may be used to ensure longer-term validity of the event data. The parameters to the handler are those of EVSimpleHandlerFunc.

Parameters

cm	The CManager from which this stone was allocated.
stone	The stone to which to register the action.
format_list	The list of formats which describe the event data structure that the function accepts.
handler	The handler function that will be called with data arrives.
client_data	An uninterpreted value that is passed to the handler function when it is called.

Returns: An action identifier, an integer EVaction value, which can be used in subsequent calls to modify or remove the action.

EVaction EVassoc_raw_terminal_action	(	CManager	cm,
		EVstone	stone,
		EVRawHandlerFunc	handler,
		void *	client_data
	)

Associate a raw terminal action (sink) with a stone.

The specified handler will be called when any data. Data is delivered in FFS-encoded form using the EVRawHandlerFunc interface. The event data supplied may not remain valid after the handler call returns. EVtake_event_buffer() may be used to ensure longer-term validity of the event data. The parameters to the handler are those of EVRawHandlerFunc.

Parameters

cm	The CManager from which this stone was allocated.
stone	The stone to which to register the action.
handler	The handler function that will be called with data arrives.
client_data	An uninterpreted value that is passed to the handler function when it is called.

Returns: An action identifier, an integer EVaction value, which can be used in subsequent calls to modify or remove the action.

EVstone EVcreate_terminal_action	(	CManager	cm,
		FMStructDescList	format_list,
		EVSimpleHandlerFunc	handler,
		void *	client_data
	)

Associate a terminal action (sink) with a new stone.

The specified handler will be called when data matching the format_list arrives at the stone. The event data supplied may not remain valid after the handler call returns. EVtake_event_buffer() may be used to ensure longer-term validity of the event data. The parameters to the handler are those of EVSimpleHandlerFunc. This function differs from the previous function only in that it creates a stone rather than using an existing stone.

Parameters

cm	The CManager from which this stone was allocated.
format_list	The list of formats which describe the event data structure that the function accepts.
handler	The handler function that will be called with data arrives.
client_data	An uninterpreted value that is passed to the handler function when it is called.

Returns: The stone identifier, an integer EVstone value, which can be used in subsequent calls.

EVaction EVassoc_multi_action	(	CManager	cm,
		EVstone	stone,
		char *	action_spec,
		void *	client_data
	)

Associate a multiple-event action with a stone.

EVassoc_multi_action() can be used to install handlers which potentially consume multiple events as input and will not necessarily consume any event immediately. In evpath, these handlers are run whenever a new event arrives in their queue, but that handler must explicitly dequeue an event to consume it. There is no declaration of conditions under which a handler is to run. It is expected to inspect its queue upon activation and simply return without action if conditions are not suitable for it to act (I.E. it needs more events, a different set of events, etc.). While the stone has only one real queue, events in that queue are segregated into the types specified in the action_spec and presented as being in multiple queues.

Parameters

cm	The CManager from which this stone was allocated.
stone	The stone to which to register the action.
action_spec	An action specification of the sort created by create_multityped_action_spec().
client_data	An uninterpreted value that is passed to the handler function when it is called.

Returns: An action identifier, an integer EVaction value, which can be used in subsequent calls to modify or remove the action.

EVaction EVassoc_immediate_action	(	CManager	cm,
		EVstone	stone,
		char *	action_spec,
		void *	client_data
	)

Associate an immediate non-terminal action with a stone.

EVassoc_immediate_action() can be used to install handlers which take only a single event as input and can therefore run and "consume" their data immediately. In particular, they are distinct from actions which may leave their input data enqueued for some time (typically handlers which might require more than one event to act). The current EVPath implementation supports only immediate actions with one input and one output, but multiple output actions will be implemented soon.

Parameters

cm	The CManager from which this stone was allocated.
stone	The stone to which to register the action.
action_spec	An action specification of the sort created by create_filter_action_spec() or create_transform_action_spec().
client_data	An uninterpreted value that is passed to the handler function when it is called.

Returns: An action identifier, an integer EVaction value, which can be used in subsequent calls to modify or remove the action.

EVstone EVcreate_immediate_action	(	CManager	cm,
		char *	action_spec,
		EVstone *	target_list
	)

Associate an immediate non-terminal action with a new stone.

EVassoc_immediate_action() can be used to install handlers which take only a single event as input and can therefore run and "consume" their data immediately. In particular, they are distinct from actions which may leave their input data enqueued for some time (typically handlers which might require more than one event to act). The current EVPath implementation supports only immediate actions with one input and one output, but multiple output actions will be implemented soon. This function differs from the previous function only in that it creates a stone rather than using an existing stone.

Parameters

cm	The CManager from which this stone was allocated.
action_spec	An action specification of the sort created by create_filter_action_spec() or create_transform_action_spec().
target_list	A -1 terminated list of stones to which outgoing data is to be sent. This initial list can be NULL (or merely have an initial 0) to specify no targets at action initialization time. Values are filled in later with EVaction_set_output().

Returns: The stone identifier, an integer EVstone value, which can be used in subsequent calls.

int EVaction_set_output	(	CManager	cm,
		EVstone	stone,
		EVaction	action,
		int	output_index,
		EVstone	target_stone
	)

Direct the output of a stone action to another local target stone

Immediate and queued actions have one or more outputs from which data will emerge. EVaction_set_output() is used to assign each of these outputs to a local stone. (It is NOT used with output stones.)

Parameters

cm	The CManager from which this stone was allocated.
stone	The stone to which the action is registered.
action	The action whose output is to be assigned.
output_index	The zero-based index of the output to assign.
target_stone	The stone to which the specified output should be directed.

Returns: An action identifier, an integer EVaction value, which can be used in subsequent calls to modify or remove the action.

Deprecated:: Early EVPath associated output ports with actions individually, with the result that the topology of the stone graph was potentially multiplex for each action, rather than being a property of the stone. This is now changed, and all actions share the same set of output ports. When this routine is called, the action parameter is ignored, but new code should use EVstone_set_output().

int EVstone_set_output	(	CManager	cm,
		EVstone	stone,
		int	output_index,
		EVstone	target_stone
	)

Direct a particular output port of a stone to another local target stone

Immediate and queued actions have one or more outputs from which data will emerge. EVaction_set_output() is used to assign each of these outputs to a local stone. (It is NOT used with output stones.)

Parameters

cm	The CManager from which this stone was allocated.
stone	The stone to which the action is registered.
output_index	The zero-based index of the output to assign.
target_stone	The stone to which the specified output should be directed.

Returns: An action identifier, an integer EVaction value, which can be used in subsequent calls to modify or remove the action.

EVaction EVassoc_filter_action	(	CManager	cm,
		EVstone	stone,
		FMStructDescList	incoming_format_list,
		EVSimpleHandlerFunc	handler,
		EVstone	out_stone,
		void *	client_data
	)

Associate an immediate non-ECL filter action with a stone.

EVassoc_filter_action() is similar to EVassoc_immediate_action() called with an action spec generated by create_filter_action_spec(), except that a function pointer is provided directly instead of having the function generated by ECL.

Parameters

cm	The CManager from which this stone was allocated.
stone	The stone to which to register the action.
incoming_format_list	The list of formats which describe the event data structure that the function accepts.
handler	The handler function that will be called with data arrives.
out_stone	The local stone to which output should be directed.
client_data	An uninterpreted value that is passed to the handler function when it is called.

Returns: An action identifier, an integer EVaction value, which can be used in subsequent calls to modify or remove the action.

Deprecated:: This function needs to go away and instead the functionality should be integrated into a new create_*_action_spec() call that would then be passed to EVassoc_immediate_action().

EVaction EVassoc_bridge_action	(	CManager	cm,
		EVstone	stone,
		attr_list	contact_list,
		EVstone	remote_stone
	)

Associate a bridge action with a stone.

Bridge actions perform network data transmission between address spaces. EVassoc_bridge_action will acquire a CM-level connection to the remote process specified by the contact_list parameter. Data delivered to the local stone specified by stone will be encoded, sent over the network link and delivered to remote_stone in the target address space.

Parameters

cm	The CManager from which this stone was allocated.
stone	The local stone to which to register the action.
contact_list	A CM-level contact list (such as from CMget_contact_list()) specifying the remote address space to connect to.
remote_stone	The stone ID in the remote address space to which data is to be delivered.

Returns: An action identifier, an integer EVaction value, which can be used in subsequent calls to modify or remove the action.

Bridge actions are associated with the default action of a stone and are non-specific as far as input data, encoding and transmitting any event presented to the action. Bridge actions may not be modified after association.

EVstone EVcreate_bridge_action	(	CManager	cm,
		attr_list	contact_list,
		EVstone	remote_stone
	)

Associate a bridge action with a new stone.

Bridge actions perform network data transmission between address spaces. EVcreate_bridge_action will acquire a CM-level connection to the remote process specified by the contact_list parameter. Data delivered to the local stone specified by stone will be encoded, sent over the network link and delivered to remote_stone in the target address space. This function differs from the previous function only in that it creates a stone rather than using an existing stone.

Parameters

cm	The CManager from which this stone was allocated.
contact_list	A CM-level contact list (such as from CMget_contact_list()) specifying the remote address space to connect to.
remote_stone	The stone ID in the remote address space to which data is to be delivered.

Returns: The stone identifier, an integer EVstone value, which can be used in subsequent calls.

Bridge actions are associated with the default action of a stone and are non-specific as far as input data, encoding and transmitting any event presented to the action. Bridge actions may not be modified after association.

EVaction EVassoc_thread_bridge_action	(	CManager	cm,
		EVstone	stone,
		CManager	target_cm,
		EVstone	target_stone
	)

Associate a thread bridge action with a stone.

Thread bridge actions transfer events between CM control domains in the same address space.

Parameters

cm	The CManager from which this stone was allocated.
stone	The local stone to which to register the action.
target_cm	Another CManager in the same address space to which data should be transferred.
target_stone	The stone ID associated with the target CM to which data is to be delivered.

Returns: An action identifier, an integer EVaction value, which can be used in subsequent calls to modify or remove the action.

Bridge actions are associated with the default action of a stone and are non-specific as far as input data, generally transferring events without encoding or copying. Thread bridge actions may not be modified after association.

EVstone EVcreate_thread_bridge_action	(	CManager	cm,
		CManager	target_cm,
		EVstone	target_stone
	)

Associate a thread bridge action with a stone.

Thread bridge actions transfer events between CM control domains in the same address space.

Parameters

cm	The CManager from which a stone should be allocated.
target_cm	Another CManager in the same address space to which data should be transferred.
target_stone	The stone ID associated with the target CM to which data is to be delivered.

Returns: The stone identifier, an integer EVstone value, which can be used in subsequent calls.

Bridge actions are associated with the default action of a stone and are non-specific as far as input data, generally transferring events without encoding or copying. Thread bridge actions may not be modified after association.

EVaction EVassoc_split_action	(	CManager	cm,
		EVstone	stone,
		EVstone *	target_list
	)

Associate a split action with a stone.

Split actions replicate an incoming event to multiple output target stones. All output paths receive every incoming event. (Reference counts are updated, the event is not actually copied.) Split actions may be modified after association by using EVaction_add/remote_split_target() to modify the target list.

Parameters

cm	The CManager from which this stone was allocated.
stone	The local stone to which to register the action.
target_list	A '-1' terminated list of stones to which incoming data is to be replicated. This initial list can be NULL (or merely have an initial '-1') to specify no targets at action initialization time.

Returns: An action identifier, an integer EVaction value, which can be used in subsequent calls to modify or remove the action.

EVstone EVcreate_split_action	(	CManager	cm,
		EVstone *	target_list
	)

Associate a split action with a new stone.

Split actions replicate an incoming event to multiple output target stones. All output paths receive every incoming event. (Reference counts are updated, the event is not actually copied.) Split actions may be modified after association by using EVaction_add/remote_split_target() to modify the target list. This function differs from the previous function only in that it creates a stone rather than using an existing stone.

Parameters

cm	The CManager from which this stone was allocated.
target_list	A '-1' terminated list of stones to which incoming data is to be replicated. This initial list can be NULL (or merely have an initial -1) to specify no targets at action initialization time.

Returns: The stone identifier, an integer EVstone value, which can be used in subsequent calls.

int EVaction_add_split_target	(	CManager	cm,
		EVstone	stone,
		EVaction	action,
		EVstone	target_stone
	)

Add a target to a split action.

This call adds a new target stone to the list of stones to which a split action will replicate data.

Parameters

cm	The CManager from which this stone was allocated.
stone	The split stone.
action	The split action ID (as returned by EVassoc_split_action()).
target_stone	The target stone to add to the list.

Returns: Returns 1 on success, 0 on failure (fails if there is not a split action on the specified stone).

void EVaction_remove_split_target	(	CManager	cm,
		EVstone	stone,
		EVaction	action,
		EVstone	target_stone
	)

Remove a target from a split action.

This call removes a target stone from the list of stones to which a split action will replicate data.

Parameters

cm	The CManager from which this stone was allocated.
stone	The split stone.
action	The split action ID (as returned by EVassoc_split_action()).
target_stone	The target stone to remove from the list.

void EVstone_add_split_target	(	CManager	cm,
		EVstone	stone,
		EVstone	target_stone
	)

Add a particular target to any split action associated with a stone.

This call adds a target stone to the list of stones to which a split action will replicate data.

Parameters

cm	The CManager from which this stone was allocated.
stone	The split stone.
target_stone	The target stone to add to the list.

void EVstone_remove_split_target	(	CManager	cm,
		EVstone	stone,
		EVstone	target_stone
	)

Remove a particular target from any split action associated with a stone.

This call removes a target stone from the list of stones to which a split action will replicate data.

Parameters

cm	The CManager from which this stone was allocated.
stone	The split stone.
target_stone	The target stone to remove from the list.

EVaction EVassoc_congestion_action	(	CManager	cm,
		EVstone	stone,
		char *	action_spec,
		void *	client_data
	)

Associate a congestion-event action with an output stone.

EVassoc_congestion_action() can be used to install a handler which should run when the events queued on an output stone cannot be transmitted immediately (usually because of network congestion). Like the multi_action, there is only real queue for output stones, but for congestion actions events in that queue are segregated into the types specified in the action_spec and presented as being in multiple queues.

Parameters

cm	The CManager from which this stone was allocated.
stone	The stone to which to register the action.
action_spec	An action specification of the sort created by create_multityped_action_spec().
client_data	An uninterpreted value that is passed to the handler function when it is called.

Returns: An action identifier, an integer EVaction value, which can be used in subsequent calls to modify or remove the action.

EVstone EVcreate_store_action	(	CManager	cm,
		EVstone	out_stone,
		int	store_limit
	)

Create a new storage stone.

Store stone buffer up to a limit of events temporarily, and send the event to out_stone when done.

Parameters

cm	The CManager from which this stone is allocated.
out_stone	The target stone for output
store_limit	The maximum number of events to buffer (when this limit is reached events will be passed through)

Returns: The newly allocated stone.

EVstone EVcreate_stone_action	(	CManager	cm,
		char *	action_spec
	)

Create a new stone with a general action.

This is the non-specific action stone creation call

Parameters

cm	The CManager from which this stone is allocated.
action_spec	The spec returned from some create_*_action_spec() call

Returns: The newly allocated stone.

EVaction EVassoc_store_action	(	CManager	cm,
		EVstone	stone_num,
		EVstone	out_stone,
		int	store_limit
	)

Create a new storage action.

Storage actions implement storage stones internally and will accept any type of event.

Parameters

cm	The CManager from which the stone is allocated
stone_num	The stone to add the action to.
out_stone	The stone buffered data will be sent to when done.
store_limit	The maximum number of events to store. Set to -1 for no limit. Stone will ordinarily act like a a buffer with this maximum size when the limit is reached.

Returns: The number of the newly created action.

void EVclear_stored	(	CManager	cm,
		EVstone	stone_num,
		EVaction	action_num
	)

Clear the contents stored in the specified storage action.

Parameters

cm	The CManager from which the stone is allocated
stone_num	The stone the action is attached to
action_num	The action created

void EVsend_stored	(	CManager	cm,
		EVstone	stone_num,
		EVaction	action_num
	)

Send the contents stored in the specified storage action. The storage will be empty when this function returns.

Parameters

cm	The CManager from which the stone is allocated
stone_num	The stone the action is attached to
action_num	The action created

int EVstore_count	(	CManager	cm,
		EVstone	stone_num,
		EVaction	action_num
	)

Count the number of items stored in a storage action.

Parameters

cm	The CManager from which the stone is allocated
stone_num	The stone the action is attached to
action_num	The action created (return value of EVassoc_store_action())

Returns: Number of events stored

int EVstore_is_sending	(	CManager	cm,
		EVstone	stone_num,
		EVaction	action_num
	)

Return whether we are sending from this storage stone.

Parameters

cm	The CManager from which this stone is allocated.
stone_num	The stone the action is attached to
action_num	The action created

Returns: True iff currently sending

void EVstore_start_send	(	CManager	cm,
		EVstone	stone_num,
		EVaction	action_num
	)

Start sending from a storage stone. Will not stop until done sending.

Parameters

cm	The CManager from which this stone is allocated.
stone_num	The stone the action is attached to
action_num	The action created

void EVset_store_limit	(	CManager	cm,
		EVstone	stone_num,
		EVaction	action_num,
		int	store_limit
	)

Set the maximum number of items stored in a storage stone, when using it like a buffer. Excess items will be flushed to the next stone in line.

Parameters

cm	The CManager from which the stone is allocated
stone_num	Which stone the action is attached to
action_num	The storage action
store_limit	The maximum number of events to keep buffered

EVsource EVcreate_submit_handle	(	CManager	cm,
		EVstone	stone,
		FMStructDescList	data_format
	)

Create a submission handle (EVsource).

EVpath is optimized for repetitive event streams. Rather than specifying the characteristics of data and the stone to which it is to be submitted on every event submission, we use associate those characteristics with EVsource handles. These handles serve as a cache for internal information.

Parameters

cm	The CManager associated with the stone.
stone	The stone to which data is to be submitted.
data_format	The FMStructDescList describing the representation of the data.

Returns: An EVsource handle for use in later EVsubmit() calls.

Examples:: dfg_client.c, dfg_client3.c, dfg_master.c, dfg_master2.c, dfg_master3.c, and dfg_master4.c.

void EVfree_source ( EVsource source )

Free a source.

This call free's the resources associated with an EVsource handle..

Parameters

source The source to free.

EVsource EVcreate_submit_handle_free	(	CManager	cm,
		EVstone	stone,
		FMStructDescList	data_format,
		EVFreeFunction	free_func,
		void *	client_data
	)

Create a submission handle (EVsource), specifying a free function for the event.

EVpath is optimized for repetitive event streams. Rather than specifying the characteristics of data and the stone to which it is to be submitted on every event submission, we use associate those characteristics with EVsource handles. These handles serve as a cache for internal information. This version of the call allows an EVFreeFunction to be associated with the handle. EVpath will take ownership of the submitted data, calling the free function when processing is finished.

Parameters

cm	The CManager associated with the stone.
stone	The stone to which data is to be submitted.
data_format	The FMStructDescList describing the representation of the data.
free_func	The EVFreeFunction to call when EVPath has finished processing the submitted data.
client_data	The parameter is supplied to the free function and can be used to supply it with additional information.

Returns: An EVsource handle for use in later EVsubmit() calls.

void EVsubmit	(	EVsource	source,
		void *	data,
		attr_list	attrs
	)

Submit an event for processing by EVPath.

EVsubmit submits an event for processing by EVPath. The format of the submitted data must match the description given by the data_format parameter when the EVsource handle was created. The attrs parameter specifies the attributes (name/value pairs) that the event is submitted with. These attributes will be delivered to the final terminal, as well as being available at intermediate processing points. Some attributes may affect the processing or transmission of data, depending upon the specific transport or processing agents.

Parameters

source	The EVsource handle through which data is to be submitted.
data	The data to be submitted, represented as a void*.
attrs	The attribute list to be submitted with the data.

Examples:: dfg_client.c, dfg_client3.c, dfg_master.c, dfg_master2.c, dfg_master3.c, and dfg_master4.c.

void EVsubmit_general	(	EVsource	source,
		void *	data,
		EVFreeFunction	free_func,
		attr_list	attrs
	)

Submit an event for processing by EVPath.

EVsubmit submits an event for processing by EVPath. The format of the submitted data must match the description given by the data_format parameter when the EVsource handle was created. The attrs parameter specifies the attributes (name/value pairs) that the event is submitted with. These attributes will be delivered to the final terminal, as well as being available at intermediate processing points. Some attributes may affect the processing or transmission of data, depending upon the specific transport or processing agents.

Parameters

source	The EVsource handle through which data is to be submitted.
data	The data to be submitted, represented as a void*.
free_func	The EVFreeFunction to call when EVPath has finished processing the submitted data.
attrs	The attribute list to be submitted with the data.

Deprecated:: This function is used to underly ECho, which allows the free function to be specified with the submit. New applications should specify the free function in the submit handle.

void EVsubmit_encoded	(	CManager	cm,
		EVstone	stone,
		void *	data,
		int	data_len,
		attr_list	attrs
	)

Submit a pre-encoded event for processing by EVPath.

EVsubmit submits a pre-encoded event for processing by EVPath. The event must be a contiguous FFS-encoded block of data. The attrs parameter specifies the attributes (name/value pairs) that the event is submitted with. These attributes will be delivered to the final terminal, as well as being available at intermediate processing points. Some attributes may affect the processing or transmission of data, depending upon the specific transport or processing agents.

Parameters

cm	The CManager associated with the stone.
stone	The stone to which data is to be submitted.
data	The pre-encoded data to be submitted, represented as a void*.
data_len	The length of the pre-encoded data block.
attrs	The attribute list to be submitted with the data.

int EVtransfer_events	(	CManager	cm,
		EVstone	src_stone,
		EVstone	dest_stone
	)

Submit a pre-encoded event for processing by EVPath.

EVtransfer_events will dequeue events in the incoming data queue associated with the src_stone parameter and re-enqueue them on the dest_stone.

Parameters

cm	The CManager associated with the stone.
src_stone	The stone from which events are to be removed
dest_stone	The stone to which events are to transfered

Returns: -1 on error, otherwise count of events transferred on success;

int EVtake_event_buffer	(	CManager	cm,
		void *	event
	)

Assume control over a incoming buffer of data.

This call is designed to be used inside a EVSimpleHandlerFunc. Normally data buffers are recycled and EVPath only guarantees that the data data delivered to an EVSimpleHandlerFunc will be valid for the duration data of the call. In that circumstance, a handler that wanted to data preserve the data for longer than its own duration (to pass it to a data thread or enter it into some other data structure for example) would data have to copy the data. To avoid that inefficiency, EVtake_event_buffer() allows the handler to take control of the buffer holding its incoming data. The buffer will then not be recycled until it is returned to CM with EVreturn_event_buffer().

Parameters

cm	The CManager in which the handler was called.
event	The base address of the data (I.E. the message parameter to the EVSimpleHandlerFunc).

Returns: 0 on error, 1 on success;

void EVreturn_event_buffer	(	CManager	cm,
		void *	event
	)

Return a buffer of incoming data.

This call recycles a data buffer that the application has taken control of through EVtake_event_buffer().

Parameters

cm	The CManager in which the handler was called.
event	The base address of the data (I.E. same value that was passed to EVtake_event_buffer().

FMFormat EVget_src_ref_format ( EVsource source )

return the FFSDataHandle associated with an EVsource handle.

Some middleware may find it useful to access the FMFormat that is produced when the FMStructDescList associated with a source is registered with FFS. This call merely gives access to that information to save a reregistration step.

Parameters

source The EVsource value for which to retrieve the associated FMFormat.

void EVenable_auto_stone	(	CManager	cm,
		EVstone	stone_num,
		int	period_sec,
		int	period_usec
	)

Enable periodic auto-submits of NULL events on a stone.

Parameters

cm	The CManager in which the stone is registered.
stone_num	The stone which should receive auto-submits.
period_sec	The period at which submits should occur, seconds portion.
period_usec	The period at which submits should occur, microseconds portion.

EVstone EVcreate_auto_stone	(	CManager	cm,
		int	period_sec,
		int	period_usec,
		char *	action_spec,
		EVstone	out_stone
	)

Enable periodic auto-submits of NULL events on a stone. This function differs from the previous function only in that it creates a stone rather than using an existing stone.

Parameters

cm	The CManager in which the stone is registered.
period_sec	The period at which submits should occur, seconds portion.
period_usec	The period at which submits should occur, microseconds portion.
action_spec	An action specification of the sort created by create_filter_action_spec() or create_transform_action_spec().
out_stone	The local stone to which output should be directed.

Returns: The stone identifier, an integer EVstone value, which can be used in subsequent calls.

void EVstall_stone	(	CManager	cm,
		EVstone	stone_id
	)

Cause a stone to become "stalled" explicitly. In this state, the stone will continue processing events as usual, but will propagate backpressure as if it were overloaded.

A stone marked as stalled with EVstall_stone will remain stalled even as other sources of stalling (remote squelching, too many queued but unprocessed events) change.

Parameters

cm	The CManager in which the stone is registered
stone_id	The stone to be marked as stalled

void EVunstall_stone	(	CManager	cm,
		EVstone	stone_id
	)

Undo EVstall_stone(), allowing the stone to become unstalled when other reasons for stalling are not present.

Parameters

cm	The CManager in which the stone is registered
stone_id	The stone to unmark as stalled, which should have been marked as stalled with EVstall_stone()

int EVsubmit_or_wait	(	EVsource	source,
		void *	data,
		attr_list	attrs,
		EVSubmitCallbackFunc	cb,
		void *	user_data
	)

If the stone pointed to by the source handle is not stalled, submit normally and return true; otherwise, return false and call the supplied callback when it is no longer stalled.

Parameters

source	The EVsource handle through which data is to be submitted.
data	The data to be submitted, represented as a void*.
attrs	The attribute list to be submitted with the data.
cb	The function to call if the submit cannot be performed now.
user_data	Passed as a parameter to the callback.

int EVsubmit_encoded_or_wait	(	CManager	cm,
		EVstone	stone,
		void *	data,
		int	data_len,
		attr_list	attrs,
		EVSubmitCallbackFunc	cb,
		void *	user_data
	)

As EVsubmit_or_wait, but as if calling EVsubmit_encoded.

Parameters

cm	The CManager with which the target stone is registered
stone	The target stone id
data	The data to be submitted, represented as a void*.
data_len	The length of the pre-encoded data.
attrs	The attribute list to be submitted with the data.
cb	The function to call if the submit cannot be performed now.
user_data	Passed as a parameter to the callback.

int EVfreeze_stone	(	CManager	cm,
		EVstone	stone_id
	)

Cause a stone to suspend operation

This function causes a stone to enter a "suspended" state in which incoming data will simply be queued, rather than submitted to any actions which might be registered. In the case of an output stone, will allow the stone to finish the output action it is currently executing and then prevent the output stone from sending any more data to the target stone.

Parameters

cm	The CManager in which the stone is registered
stone_id	The stone which is to be frozen

Returns: Returns 1 on success, 0 on failure

int EVunfreeze_stone	(	CManager	cm,
		EVstone	stone_id
	)

Cause a stone to resume operation

This function causes a frozen stone (via EVfreeze_stone()) to resume operation. Pending data will be submitted to actions during the next action processing phase.

Parameters

cm	The CManager in which the stone is registered
stone_id	The stone to unfreeze

Returns: Returns 1 on success, 0 on failure

int EVdrain_stone	(	CManager	cm,
		EVstone	stone_id
	)

Drain a stone

This function is a blocking call that suspends the caller until all events queued on a stone are processed (if processing is possible, it might not be for events that require the presence of other events). The function is typically used after upstream stones have been frozen with EVfreeze_stone() during a reconfiguration action. EVdrain_stone() then makes sure a stone is as empty as possible prior to event extraction and destruction.

Parameters

cm	The CManager in which the stone is registered
stone_id	The stone which is to be drained

Returns: Returns 1 on success, 0 on failure

EVstone EVexecuting_stone ( CManager cm )

Return the EVstone id inside an executing terminal handler

If called from within an executing terminal handler or a function called by a terminal handler, this function will return the EVstone ID of the stone with home that handler was registered. Generally, the client_data parameter in EVcreate/assoc_terminal_action() is the best way to pass information to a handler, but in EVdfg a handler is registered once by name and may be assigned to multiple stones. This function provides a way to differentiate between those stones during execution and to access items such as the attribute list associated with those stones.

Parameters

cm	The CManager in which the function is currently executing

Returns: The stone ID of the stone in whose handler we're executing (or -1 on error)

EVevent_list EVextract_stone_events	(	CManager	cm,
		EVstone	stone_id
	)

Return the queued events associated with a stone and its actions.

This function will be called by EVdrain_stone. It will form an array of structures where each structure will contain the size of the encoded event and a pointer to the encoded event. The array will contain an entry for each event, associated with the stone or its actions.

Parameters

cm	The CManager in which the stone is registered
stone_id	The stone whose associated events are to be extracted

Returns: Returns an array of structures (EVevent_list) containing the lengths of events and pointers to the encoded versions of events

attr_list EVextract_attr_list	(	CManager	cm,
		EVstone	stone_id
	)

Return the attribute list associated with a stone.

This function is used to extract the set of attributes associated with a stone. It is normally used during a reconfiguration operation to recreate a stone elsewhere.

Parameters

cm	The CManager in which the stone is registered
stone_id	The stone whose attributes are to be extracted

Returns: attr_list Returns the attribute list associated with the stone

void EVset_attr_list	(	CManager	cm,
		EVstone	stone_id,
		attr_list	list
	)

Set the attribute list associated with a stone.

This function is used to set the attributes associated with a stone. It is normally used during a reconfiguration operation to recreate a stone elsewhere.

Parameters

cm	The CManager in which the stone is registered
stone_id	The stone whose attributes are to be extracted
list	The attribute list to be associated with the stone

int EVdestroy_stone	(	CManager	cm,
		EVstone	stone_id
	)

Free a stone after it has been drained.

This function will wait till a stone is drained. Then it will free all the data and events associated with the stone.

Parameters

cm	The CManager in which the stone is registered
stone_id	The stone which is to be destroyed

Returns: Returns 1 on success, 0 on failure

char* create_filter_action_spec	(	FMStructDescList	format_list,
		char *	function
	)

create an action specification for a filter function.

Parameters

format_list	A description of the incoming event data that the filter expects.
function	The filter function itself. A zero return value means that the data should be discarded.

char* create_router_action_spec	(	FMStructDescList	format_list,
		char *	function
	)

create an action specification for a router function.

Parameters

format_list	A description of the incoming event data that the router function expects.
function	The router function itself. A negative return value means that the data should be discarded. A positive value less than the number of output values that have been set with EVaction_set_output() indicates which of the output paths the input data should be submitted to. Return values larger than the number of output paths have undefined behavior.

char* create_transform_action_spec	(	FMStructDescList	format_list,
		FMStructDescList	out_format_list,
		char *	function
	)

create an action specification that transforms event data.

Parameters

format_list	A description of the incoming event data that the transformation expects.
out_format_list	A description of the outgoing event data that the transformation will produce.
function	The processing that will perform the transformation. A zero return value means that the output data should be ignored/discarded.

char* create_multityped_action_spec	(	FMStructDescList *	input_format_lists,
		char *	function
	)

create an action specification that operates on multiple queues of events

Parameters

input_format_lists	A null-terminated list of null-terminated lists of descriptions of the incoming event data types that the transformation expects.
function	The processing that will perform the transformation. Not outputs are explicit, but must be performed by some EVsubmit* action.

void EVadd_dll_search_dir ( char * path_string )

Add a directory to search for DLL-based functions

Parameters

path_string The name of a directory to include for searches

void EVadd_standard_structs	(	CManager	cm,
		FMStructDescList *	lists
	)

Add a set of structure types that will be visible in COD.

Parameters

cm	The CManager in which the routines should be visible
lists	A NULL-terminated list of FMStructDescLists.

void EVregister_close_handler	(	CManager	cm,
		EVStoneCloseHandlerFunc	handler,
		void *	client_data
	)

Register a handler to be called when a bridge stone is closed

Parameters

cm	The CManager managing the bridge stones
handler	The routine to be called
client_data	This parameter will be supplied unmodified to the handler routine upon close.

void EVdump_stone	(	CManager	cm,
		EVstone	stone_num
	)

Print a description of stone status to standard output.

A simple dump function that can be used for debugging.

Parameters

cm	The CManager to which the stone is registered.
stone_num	The stone to dump.

void EVassoc_conversion_action	(	CManager	cm,
		int	stone_id,
		int	stage,
		FMFormat	target_format,
		FMFormat	incoming_format
	)

Associate a conversion action.

This function is used by the EVPath internal "response" interface. At some point, the response interface will likely become external so that EVPath's response to unknown data can be customized. However, at the moment this is an internal interface.

attr_list CMtest_transport	(	CMConnection	conn,
		attr_list	how
	)

Perform a transport-level bandwidth test

This function requests that EVPath perform a transport-level performance check (currently of bandwidth) by sending a series of messages of a fixed size, broken up internally into a fixed number of vectors (a la writev()). Th nature of the test is controlled by the 'how' attribute list parameter. In particular, the CM_TRANS_TEST_SIZE attribute controls the message size in bytes, the CM_TRANS_TEST_VECS attribute specifies how many vectors the message is to be broken up into (each vector will be roughly size/vectors in bytes), and CM_TRANS_TEST_REPEAT gives the total number of messages to send. The total number of bytes sent will be size

repeat_count. The return attribute list value will contain at least the following double-valued attributes, CM_TRANS_TEST_DURATION - containing the duration of the test in seconds, and CM_TRANS_MEGABITS_SEC
containing the estimated bandwidth in megabits per sec. I.E. size * repeat_count * 8 / 1000 * 1000 * secs. Note the "bits", not bytes, and that we use 1000 rather than 1024 to more closely match networking conventions.

Parameters

conn	The CMConnection on which to perform the bandwidth test
how	Parameters to control the bandwidth test

void CMinstall_perf_upcall	(	CManager	cm,
		CMperf_upcall	upcall
	)

install the callback function to support transport testing

CMinstall_perf_upcall() sets up an upcall to be used when CMtest_transport() initiates a transport-level performance test.

Parameters

cm	The CManager in which to register the upcall.
upcall	The function to be called when a performance message arrives.

Typedefs

Functions

Detailed Description

Typedef Documentation

Function Documentation