|
EVPath
|
Macros | |
| #define | DFG_SOURCE -1 |
| #define | DFG_STATUS_SUCCESS 0 |
| #define | DFG_STATUS_FAILURE 1 |
Typedefs | |
| typedef struct _EVdfg * | EVdfg |
| typedef struct _EVmaster * | EVmaster |
| typedef struct _EVclient * | EVclient |
| typedef struct _EVdfg_stone * | EVdfg_stone |
| typedef struct _EVclient_sources * | EVclient_sources |
| typedef struct _EVclient_sinks * | EVclient_sinks |
| typedef void(* | EVmasterJoinHandlerFunc )(EVmaster master, char *identifier, void *available_sources, void *available_sinks) |
| typedef void(* | EVmasterFailHandlerFunc )(EVdfg dfg, char *failed_client, int failed_stone) |
| typedef void(* | EVmasterReconfigHandlerFunc )(EVdfg dfg) |
| #define DFG_SOURCE -1 |
Special StoneID used in EVcreate_submit_handle()
DFG_SOURCE is a special StoneID used in calls to EVcreate_submit_handle() to create EVsource handles that can be later assigned to DFG source nodes.
| #define DFG_STATUS_SUCCESS 0 |
a value used in EVclient shutdown calls
DFG_STATUS_SUCCESS is a value used in EVclient_shutdown* calls
| #define DFG_STATUS_FAILURE 1 |
a value used in EVclient shutdown calls
DFG_STATUS_FAILURE is a value used in EVclient_shutdown* calls
| typedef struct _EVdfg* EVdfg |
EVdfg is a handle to a DFG.
EVdfg is an opaque handle
| typedef struct _EVmaster* EVmaster |
EVmaster is a handle to a DFG master, the distinguished process who creates the DFGs and manages clients.
EVmaster is an opaque handle
| typedef struct _EVclient* EVclient |
EVclient is a handle to a client process which can host DFG components.
EVclient is an opaque handle
| typedef struct _EVdfg_stone* EVdfg_stone |
EVdfg_stone is a handle to virtual EVpath stone.
EVdfg_stone is an opaque handle.
| typedef struct _EVclient_sources* EVclient_sources |
EVclient_sources is a handle to the set of client event source capabilities.
This opaque handle is returned by EVclient_register_source() and is then specified to EVclient_assoc() or EVclient_assoc_local(). It represents the capabilities of this client to host event source stones for any DFG that might be created.
| typedef struct _EVclient_sinks* EVclient_sinks |
EVclient_sources is a handle to the set of client event handler capabilities.
This opaque handle is returned by EVclient_register_sink_handler() or EVclient_register_raw_sink_handler() and is then specified to EVclient_assoc() or EVclient_assoc_local(). It represents the handlers available on this client for use by event sink stones for any DFG that might be created.
| typedef void(* EVmasterJoinHandlerFunc)(EVmaster master, char *identifier, void *available_sources, void *available_sinks) |
The prototype for an EVmaster client-join handling function.
In "dynamic join" mode, as opposed to static-client-list mode (See EVmaster_register_node_list()), the EVdfg master calls a registered join handler each time a new client node joins the DFG. This handler should 1) potentially assign a canonical name to the client node (using EVmaster_assign_canonical_name()), and 2) when the expected nodes have all joined the handler should create the virtual DFG and then call EVdfg_realize() in order to instantiate it.
This call happens in the Master process only.
| dfg | The EVdfg handle with which this handler is associated |
| identifier | This null-terminated string is the value specified in the corresponding EVclient_assoc() call by a client. |
| available_sources | This parameter is currently a placeholder for information about what sources the client is capable of hosting. |
| available_sinks | This parameter is currently a placeholder for information about what sinks the client is capable of hosting. |
| typedef void(* EVmasterFailHandlerFunc)(EVdfg dfg, char *failed_client, int failed_stone) |
The prototype for an EVdfg client-fail handling function.
If the an EVmasterFailHandlerFunc has been registered to the DFG, this function will be called in the event that some node has failed. Generally EVdfg becomes aware that a node has failed when some other client tries to do a write to a bridge stone connected to that node and that write fails. Three things to be cognizant of:
| dfg | The EVdfg handle with which this handler is associated |
| failed_client | This null-terminated string is the value that was specified in EVclient_assoc() in the failed client. |
| failed_stone | This is local ID of the failed stone (perhaps not useful to anyone - should change or eliminate this). |
| typedef void(* EVmasterReconfigHandlerFunc)(EVdfg dfg) |
The prototype for an EVdfg voluntary-reconfiguration handling function.
If the an EVmasterReconfigHandlerFunc has been registered to the DFG, this function will be called in the event that some stone has executed a call to EVdfg_trigger_reconfiguration() inside a CoD-based event handler. This allows a client application to monitor local conditions and to trigger action by the master in the event a reconfiguration is called for. The EVdfg_trigger_reconfiguration() call and the EVdfg_flush_attrs() call both cause local stone attributes to be flushed back to the Master's virtual stones so that they can be examined using EVdfg_get_attr_list().
| dfg | The EVdfg handle with which this handler is associated |
| EVmaster EVmaster_create | ( | CManager | cm | ) |
Create a DFG master
This call is used in master process to create a set of communicating EVdfg processes. The master is the unique point of control and adminstration for client processes and DFGs.
| cm | The CManager with which to associate the DFG |
| char* EVmaster_get_contact_list | ( | EVmaster | master | ) |
Get the contact list from an EVmaster handle
This call is used to extract contact information from an EVmaster handle. This call is made on the Master side of EVdfg and the contact information is then provided to the remote Clients for use in EVclient_assoc() calls. The result of this call is a null-terminated string to be owned by the caller. (I.E. you should free the string memory when you're done with it.)
| master | The EVmaster handle for which to create contact information. |
| EVclient EVclient_assoc | ( | CManager | cm, |
| char * | node_name, | ||
| char * | master_contact, | ||
| EVclient_sources | source_capabilities, | ||
| EVclient_sinks | sink_capabilities | ||
| ) |
Associate this process as a client to an EVmaster
This call is used to join the set of communicating processes as a client. The master_contact string should be the same one that came from EVmaster_get_contact_list() on the master. This call cannot be used by the master process to participate in the DFG itself. In that circumstance, EVclient_assoc_local() should be used.
The source_capabilities and sink_capabilities parameters identify the set of sinks and sources that this client is capable of hosting. Those capabilities may or may not be utilized in the DFGs created by the master. All calls to register sinks and sources should be done before the EVclient_assoc() call.
| cm | The CManager with which to associate the DFG client |
| node_name | The name with which the client can be identified. This should be unique among the joining nodes in static joining mode (I.E. using EVmaster_register_node_list(). In dynamic mode (I.E. where EVmaster_node_join_handler() is used), then this name is presented to the registered join handler, but it need not be unique. EVdfg copies this string, so it can be free'd after use. |
| master_contact | The string contact information for the master process. This is not stored by EVdfg. |
| source_capabilities | The last value returned by EVclient_register_source() or NULL |
| sink_capabilities | The last value returned by EVclient_register_sink_handle() or EVclient_register_raw_sink_handle, or NULL |
| EVclient EVclient_assoc_local | ( | CManager | cm, |
| char * | node_name, | ||
| EVmaster | master, | ||
| EVclient_sources | source_capabilities, | ||
| EVclient_sinks | sink_capabilities | ||
| ) |
Associate a client to an EVmaster in the same process
This call is for the process which hosts the EVdfg master to also participate as an EVclient.
The source_capabilities and sink_capabilities parameters identify the set of sinks and sources that this client is capable of hosting. Those capabilities may or may not be utilized in the DFGs created by the master. All calls to register sinks and sources should be done before the EVclient_assoc() call.
| cm | The CManager with which to associate the DFG client |
| node_name | The name with which the client can be identified. This should be unique among the joining nodes in static joining mode (I.E. using EVmaster_register_node_list(). In dynamic mode (I.E. where EVmaster_node_join_handler() is used), then this name is presented to the registered join handler, but it need not be unique. EVdfg copies this string, so it can be free'd after use. |
| master | The handle for the EVmaster. |
| source_capabilities | The last value returned by EVclient_register_source() or NULL |
| sink_capabilities | The last value returned by EVclient_register_sink_handle() or EVclient_register_raw_sink_handle, or NULL |
| void EVmaster_register_node_list | ( | EVmaster | master, |
| char ** | list | ||
| ) |
Supply a static list of client names to the EVmaster.
This call is used in static joining mode, that is when the set of nodes that will join the DFG client set is known upfront and each has a predefined unique name.
| master | The EVmaster handle for which the set of clients is to be specified. |
| list | A NULL-terminated list of NULL-terminated strings. These names must be unique, and each must be used in an EVclient_assoc() or EVclient_assoc_local() call before the ensemble will be complete. EVdfg copies this list, so it should be free'd by the calling application if dynamic. |
| void EVmaster_node_join_handler | ( | EVmaster | master, |
| EVmasterJoinHandlerFunc | func | ||
| ) |
Register a node join handler function to an EVmaster.
| master | The EVmaster handle with which to associate this handler |
| func | The handler function to associate |
| void EVmaster_node_fail_handler | ( | EVmaster | master, |
| EVmasterFailHandlerFunc | func | ||
| ) |
Register a node fail handler function to an EVmaster
| master | The EVmaster handle with which to associate this handler |
| func | The handler function to associate |
| void EVmaster_node_reconfig_handler | ( | EVmaster | master, |
| EVmasterReconfigHandlerFunc | func | ||
| ) |
Register a voluntary reconfiguration handler function to an EVmaster
| master | The EVmaster handle with which to associate this handler |
| func | The handler function to associate |
| void EVdfg_realize | ( | EVdfg | dfg | ) |
Cause the instantiation of a virtual DFG.
This call is performed by the master to signal the end of the creation or reorganization of a DFG. In static-client-list mode, it is generally called by master after the virtual DFG has been created. In dynamic-join mode, creating the virtual DFG and calling EVdfg_realize() is how the join handler signals EVdfg that all expected nodes have joined. In a node fail handler, a node reconfig handler, or when the join handler is called after the first realization of the DFG, a further call of EVdfg_realize() represents the finalization of a reconfiguration of the DFG.
| dfg | The handle of the EVdfg to be realized. |
| int EVclient_ready_wait | ( | EVclient | client | ) |
Wait for a DFG to be ready to run
This call is performed by participating clients (including the master process operating as a client), in order to wait for the deployment of a DFG. This call will only return after a DFG has been completely instantiated and is running. In initial deployment, all participating clients will exit this call at roughly the same time. In the case of client nodes that join after a DFG is already running, this call will return after the master has been notified of the join and the client has been incorporated into the DFG (I.E. stones potentially deployed.)
| client | The EVclient handle upon which to wait. |
| EVclient_sources EVclient_register_source | ( | char * | name, |
| EVsource | src | ||
| ) |
Associate a name with a source handle
This call is performed by client nodes in order to register their ability to host a source with the given name. If the name appears in a virtual source stone that is mapped to the client, then that source handle is active.
| name | The name to associate with the source handle. EVdfg does not take ownership of this string and the application should ensure that the string remains valid for the duration of EVdfg operation. |
| src | The EVsource to be associated with the name. Source/name association is actually an EVPath-level operation, so there is no EVdfg parameter in this call. |
| EVclient_sinks EVclient_register_sink_handler | ( | CManager | cm, |
| char * | name, | ||
| FMStructDescList | list, | ||
| EVSimpleHandlerFunc | handler, | ||
| void * | client_data | ||
| ) |
Associate a name with a sink handle
This call is performed by client nodes in order to register their ability to host a sink stone with a handler with the given name.
| cm | The client's CManager |
| name | The name to associate with the sink handle. EVdfg does not take ownership of this string and the application should ensure that the string remains valid for the duration of EVdfg operation. |
| list | The FMStructDescList describing the data that this handler function expects. EVdfg does not take ownership of this data structure and the application should ensure that the structure remains valid for the duration of EVdfg operation. |
| handler | The EVSimpleHandlerFunc to be associated with the name/data type. Sink-handle/name association is actually an EVPath-level operation, so there is a CM parameter in this call, but no EVdfg param. |
| client_data | An uninterpreted value that is passed to the handler function when it is called. |
| EVclient_sinks EVclient_register_raw_sink_handler | ( | CManager | cm, |
| char * | name, | ||
| EVRawHandlerFunc | handler, | ||
| void * | client_data | ||
| ) |
Associate a name with a raw sink handle
This call is performed by client nodes in order to register their ability to host a sink stone with a raw handler with the given name.
| cm | The client's CManager |
| name | The name to associate with the sink handle. EVdfg does not take ownership of this string and the application should ensure that the string remains valid for the duration of EVdfg operation. |
| handler | The EVRawHandlerFunc to be associated with the name/data type. Sink-handle/name association is actually an EVPath-level operation, so there is a CM parameter in this call, but no EVdfg param. |
| client_data | An uninterpreted value that is passed to the handler function when it is called. |
| int EVclient_source_active | ( | EVsource | src | ) |
return a boolean describing whether the source has been assigned in EVdfg
This call is performed by client nodes in order to determine if a particular local EVsource registered with EVdfg has actually been made active by having a virtual source stone associated with it.
| src | The source to test |
| unsigned int EVclient_active_sink_count | ( | EVclient | client | ) |
return a count of EVdfg sink stones assigned to the current client
This call is performed by client nodes in order to determine how many sink stones have been assigned to them.
| client | The EVclient under consideration. |
| int EVmaster_assign_canonical_name | ( | EVmaster | master, |
| char * | given_name, | ||
| char * | canonical_name | ||
| ) |
Assign a unique, canonical name to a client of a particular given_name.
This call is performed by the master, typically in the EVmasterJoinHandlerFunc, in order to assign a unique name to clients who may not have one previously. The canonical name is the name to be used in EVdfg_assign_node(). The only constraint on the name is that not have been assigned to any already-participating node.
| master | The master the client is joining. |
| given_name | The original name of the client. |
| canonical_name | The canonical name to be assigned to the client. |
Create a DFG
This call is used in the master process to create a DFG that will be deployed on the client processes.
| master | The EVmaster with which to associate the DFG |
| EVdfg_stone EVdfg_create_stone | ( | EVdfg | dfg, |
| char * | action_spec | ||
| ) |
Create an EVdfg stone with a specific action associated with it.
This call is performed by the master during the Stone Creation and Assignment process in order to create an EVdfg_stone.
| dfg | The DFG under consideration. |
| action_spec | An action specifier string such as is created by the EVpath create_*_action_spec() routines. This parameter may be NULL if no action is to be initially assigned to the stone. If non-NULL, EVdfg takes ownership of the action_spec string and will free it upon DFG termination. |
| void EVdfg_add_action | ( | EVdfg_stone | stone, |
| char * | action_spec | ||
| ) |
Add an action to an existing EVdfg stone.
This call is performed by the master during the Stone Creation and Assignment process in order to add an action to an EVdfg_stone.
| stone | The EVdfg_stone to which to add the action. |
| action_spec | An action specifier string such as is created by the EVpath create_*_action_spec() routines. EVdfg takes ownership of the action_spec string and will free it upon DFG termination. |
| EVdfg_stone EVdfg_create_source_stone | ( | EVdfg | dfg, |
| char * | source_name | ||
| ) |
Create an EVdfg stone that will act as an Event source.
This call is performed by the master during the Stone Creation and Assignment process in order to create an EVdfg source stone. No other actions should be assigned to an EVdfg source stone.
| dfg | The DFG under consideration. |
| source_name | This value must match some value which has been specified in EVclient_register_source() on the node to which this stone is eventually mapped. (EVdfg can't detect a mismatch until EVdfg_realize() is called.) The source_name string is not owned by EVdfg and should be free'd by the application if dynamic. |
| EVdfg_stone EVdfg_create_sink_stone | ( | EVdfg | dfg, |
| char * | handler_name | ||
| ) |
Create an EVdfg stone that will act as an Event sink (terminal stone).
This call is performed by the master during the Stone Creation and Assignment process in order to create an EVdfg sink stone.
| dfg | The DFG under consideration. |
| handler_name | This value must match some value which has been specified in EVclient_register_sink_handler() on the node to which this stone is eventually mapped. (EVdfg can't detect a mismatch until EVdfg_realize() is called.) The handler_name string is not owned by EVdfg and should be free'd by the application if dynamic. |
| void EVdfg_add_sink_action | ( | EVdfg_stone | stone, |
| char * | handler_name | ||
| ) |
Add a sink action to an existing EVdfg stone.
This call is performed by the master during the Stone Creation and Assignment process in order to add a sink (terminal) action to an EVdfg stone.
| stone | The EVdfg_stone to which to add the sink action. |
| handler_name | This value must match some value which has been specified in EVclient_register_sink_handler() on the node to which this stone is eventually mapped. (EVdfg can't detect a mismatch until EVdfg_realize() is called.) The handler_name string is not owned by EVdfg and should be free'd by the application if dynamic. |
| void EVdfg_link_port | ( | EVdfg_stone | source, |
| int | output_index, | ||
| EVdfg_stone | destination | ||
| ) |
Link a particular output port of one stone (the source) to a destination (target) stone.
This function is roughly the analog of the EVstone_set_output function, but at the EVdfg level. All non-terminal stones have one or more output ports from which data will emerge. EVdfg_link_port() is used to assign each of these outputs to another EVdfg_stone stone. For EVPath actions which have a single output, such as 'filter' and 'transform', those outputs appear on 'port_index' 0. Other actions, such as router and multityped actions allow submission to any port, so care must be taken that the code in those actions uses appropriate port numbers as assigned here. The complement of EVdfg_link_port() is EVdfg_unlink_port(). EVdfg source stones, and stones with no assigned actions, act as EVPath 'split' stones and their outputs are best managed with EVdfg_link_dest() and EVdfg_unlink_dest().
| source | The EVdfg_stone whose ports are to be assigned. |
| output_index | The zero-based index of the output which should be assigned. |
| destination | The EVdfg_stone which is to receive those events. |
| void EVdfg_link_dest | ( | EVdfg_stone | source, |
| EVdfg_stone | destination | ||
| ) |
Link an anonymous output port of one stone (the source) to a destination (target) stone.
This function is roughly the analog of the EVstone_add_split_target, but at the EVdfg level. EVdfg stones with no additional actions associated with them are implicitly EVPath split stones and events presented to their inputs are replicated to all outputs. Those outputs can be maintained by their explicit numbers (with EVdfg_link_port()), or, since the specific output port to which a target stone is assigned is unimportant, the EVdfg_link_dest() call will simply assign the target stone to the next available port. The complement to this call is EVdfg_unlink_dest().
| source | The EVdfg_stone whose ports are to be assigned. |
| destination | The EVdfg_stone which is to receive those events. |
| int EVdfg_unlink_port | ( | EVdfg_stone | source, |
| int | output_index | ||
| ) |
Unlink a particular output port of one stone (the source).
The output port should have been previously set with EVdfg_link_port.
| source | The EVdfg_stone whose ports are to be assigned. |
| output_index | The zero-based index of the output which should be assigned. |
| int EVdfg_unlink_dest | ( | EVdfg_stone | source, |
| EVdfg_stone | destination | ||
| ) |
Unlink the output port of one stone (the source) so that it no longer directs events to a particular destination (target) stone.
| source | The EVdfg_stone whose ports are to be assigned. |
| destination | The EVdfg_stone which should no longer receive those events. |
| int EVdfg_assign_node | ( | EVdfg_stone | stone, |
| char * | node | ||
| ) |
Assign a particular EVdfg_stone to a particular client node.
This function assigns a particular EVdfg_stone to be instantiated upon a particular client node. The node parameter must match either 1) a string specified in EVmaster_register_node_list() (in static joining mode), or 2) a canonical name that has been assigned to a node (in dynamic joining mode).
| stone | The EVdfg_stone to be assigned to a particular node. |
| node | The node to which it is to be assigned. EVdfg does not take ownership of this string and it should be free'd by the application if dynamic. |
| void EVdfg_enable_auto_stone | ( | EVdfg_stone | stone, |
| int | period_sec, | ||
| int | period_usec | ||
| ) |
Set virtual stone properties to enable periodic auto-submits of NULL events on an EVdfg_stone. This becomes active upon DFG realization and activation.
This function is the analog of the EVenable_auto_stone() function, but at the EVdfg level.
| stone | The EVdfg_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. |
Autosubmits are initiated on each node just as it is about to return from EVclient_ready_wait(), I.E. with DFG activation.
| void EVdfg_set_attr_list | ( | EVdfg_stone | stone, |
| attr_list | attrs | ||
| ) |
Set the attribute list that will be visible as "stone_attrs" inside EVdfg dynamic functions.
| stone | The EVdfg_stone affected. |
| attrs | The attribute list to be assigned. EVdfg does an add_ref_attr_list() on this list. Because lists are only free'd when the reference count goes to zero, the application should generally call free_attr_list() on the list as well. |
| attr_list EVdfg_get_attr_list | ( | EVdfg_stone | stone | ) |
Query the attribute list that is/was visible as "stone_attrs" inside EVdfg dynamic functions.
| stone | The EVdfg_stone involved. |
| int EVclient_shutdown | ( | EVclient | client, |
| int | result | ||
| ) |
Vote that this node is ready for shutdown, provide it's contribution to the return value and wait for the actual shutdown to occur.
One of EVclient_shutdown() or EVclient_ready_for_shutdown() should be called by every participating node for normal shutdown. The return value from all calls (on all nodes) to EVclient_shutdown() and EVclient_wait_for_shutdown() will all be the same.
| client | The EVclient handle to which a return value is contributed |
| result | this node's contribution to the DFG-wide shutdown value. In order to facilitate this value being passed directly to exit(), the convention for DFG exit values follows the Unix process exit semantics where 0 indicates success and non-zero indicates failure. In particular, the value provided should be either DFG_STATUS_SUCCESS (0) or DFG_STATUS_FAILURE (1) |
| int EVclient_force_shutdown | ( | EVclient | client, |
| int | result | ||
| ) |
Override voting and force shutdown with specific return value.
One of EVclient_shutdown() or EVclient_ready_for_shutdown() should be called by every participating node for normal shutdown. However, this call forces an abnormal shutdown. The return value from all calls (on all nodes) to EVclient_shutdown() and EVclient_wait_for_shutdown() will all the value of this result parameter.
| client | The EVclient handle for which shutdown should be forced |
| result | this node's contribution to the DFG-wide shutdown value. In order to facilitate this value being passed directly to exit(), the convention for DFG exit values follows the Unix process exit semantics where 0 indicates success and non-zero indicates failure. In particular, the value provided should be either DFG_STATUS_SUCCESS (0) or DFG_STATUS_FAILURE (1) |
| void EVclient_ready_for_shutdown | ( | EVclient | client | ) |
Vote that this node is ready for shutdown and is providing no specific contribution to the return value.
One of EVclient_shutdown() or EVclient_ready_for_shutdown() should be called by every participating node for normal shutdown. The return value from EVclient_wait_for_shutdown() will be the same on each node and will depend upon every node's contribution to the shutdown status.
| client | The EVclient handle for which shutdown is indicated. |
| int EVclient_wait_for_shutdown | ( | EVclient | client | ) |
Wait for EVdfg to determine that the coordinated shutdown time has arrived.
One of EVclient_shutdown() or EVclient_ready_for_shutdown() should be called by every participating node for normal shutdown. The return value from EVclient_wait_for_shutdown() will be the same on each node and will depend upon every node's contribution to the shutdown status.
| client | The EVclient handle for which shutdown is indicated. |
| int EVclient_test_for_shutdown | ( | EVclient | client | ) |
test to see if the coordinated shutdown time has arrived.
This call essentially tests to see if EVclient_wait_for_shutdown() will return immediately. If false, EVclient_wait_for_shutdown() would block as the coordinated shutdown time has not yet arrived. Clients using this call must still use EVclient_wait_for_shutdown() to exit cleanly.
| client | The EVclient handle for which shutdown may be imminent |
1.8.7