Main Page   Compound List   File List   Compound Members   File Members  

ce.h File Reference

#include "e_iovec.h"
#include "ce_so.h"
#include <memory.h>

Go to the source code of this file.

Compounds

struct  ce_jops_t
struct  ce_local_state_t
struct  ce_view_id_t
struct  ce_view_state_t

Defines

#define __CE_H__
#define CE_DEFAULT_PROTOCOL   "Top:Heal:Switch:Leave:Inter:Intra:Elect:Merge:Slander:Sync:Suspect:Stable:Vsync:Frag_Abv:Top_appl:Frag:Pt2ptw:Mflow:Pt2pt:Mnak:Bottom"
#define CE_DEFAULT_PROPERTIES   "Gmp:Sync:Heal:Switch:Frag:Suspect:Flow:Slander"
#define record_create(type, var)   ((type)malloc(sizeof(*var)))
#define record_free(rec)   free(rec)
#define record_clear(rec)   memset(rec, 0, sizeof(*rec))

Typedefs

typedef double ce_float_t
typedef int ce_bool_t
typedef int ce_rank_t
typedef int ce_ltime_t
typedef int ce_len_t
typedef void* ce_env_t
typedef double ce_time_t
typedef char* ce_endpt_t
typedef char* ce_addr_t
typedef char* ce_data_t
typedef ce_iovec_t* ce_iovec_array_t
typedef ce_bool_tce_bool_array_t
typedef ce_endpt_tce_endpt_array_t
typedef ce_rank_tce_rank_array_t
typedef ce_addr_tce_addr_array_t
typedef struct ce_view_id_t  ce_view_id_t
typedef ce_view_id_t** ce_view_id_array_t
typedef struct ce_view_state_t  ce_view_state_t
typedef struct ce_local_state_t  ce_local_state_t
typedef struct ce_jops_t  ce_jops_t
typedef void (* ce_appl_install_t )(ce_env_t, ce_local_state_t *, ce_view_state_t *)
typedef void (* ce_appl_exit_t )(ce_env_t)
typedef void (* ce_appl_receive_cast_t )(ce_env_t, ce_rank_t, int, ce_iovec_array_t)
typedef void (* ce_appl_receive_send_t )(ce_env_t, ce_rank_t, int, ce_iovec_array_t)
typedef void (* ce_appl_flow_block_t )(ce_env_t, ce_rank_t, ce_bool_t)
typedef void (* ce_appl_block_t )(ce_env_t)
typedef void (* ce_appl_heartbeat_t )(ce_env_t, ce_time_t)
typedef struct ce_appl_intf_t ce_appl_intf_t
typedef int CE_SOCKET
typedef void (* ce_handler_t )(void *)
typedef void (* ce_appl_flat_receive_cast_t )(ce_env_t, ce_rank_t, ce_len_t, ce_data_t)
typedef void (* ce_appl_flat_receive_send_t )(ce_env_t, ce_rank_t, ce_len_t, ce_data_t)

Functions

LINKDLL char* ce_copy_string (char *str)
LINKDLL void ce_view_full_free (ce_local_state_t *ls, ce_view_state_t *vs)
LINKDLL void ce_jops_free (ce_jops_t *)
LINKDLL ce_appl_intf_tce_create_intf (ce_env_t env, ce_appl_exit_t exit, ce_appl_install_t install, ce_appl_flow_block_t flow_block, ce_appl_block_t block, ce_appl_receive_cast_t cast, ce_appl_receive_send_t send, ce_appl_heartbeat_t heartbeat)
LINKDLL void ce_Init (int argc, char **argv)
LINKDLL void ce_Main_loop (void)
LINKDLL void ce_Join (ce_jops_t *ops, ce_appl_intf_t *c_appl)
LINKDLL void ce_Leave (ce_appl_intf_t *c_appl)
LINKDLL void ce_Cast (ce_appl_intf_t *c_appl, int num, ce_iovec_array_t iovl)
LINKDLL void ce_Send (ce_appl_intf_t *c_appl, int num_dests, ce_rank_array_t dests, int num, ce_iovec_array_t iovl)
LINKDLL void ce_Send1 (ce_appl_intf_t *c_appl, ce_rank_t dest, int num, ce_iovec_array_t iovl)
LINKDLL void ce_Prompt (ce_appl_intf_t *c_appl)
LINKDLL void ce_Suspect (ce_appl_intf_t *c_appl, int num, ce_rank_array_t suspects)
LINKDLL void ce_XferDone (ce_appl_intf_t *c_appl)
LINKDLL void ce_Rekey (ce_appl_intf_t *c_appl)
LINKDLL void ce_ChangeProtocol (ce_appl_intf_t *c_appl, char *protocol_name)
LINKDLL void ce_ChangeProperties (ce_appl_intf_t *c_appl, char *properties)
LINKDLL void ce_MLPrintOverride (void(*handler)(char *msg))
LINKDLL void ce_MLUncaughtException (void(*handler)(char *info))
LINKDLL void ce_AddSockRecv (CE_SOCKET socket, ce_handler_t handler, ce_env_t env)
LINKDLL void ce_RmvSockRecv (CE_SOCKET socket)
LINKDLL ce_appl_intf_tce_create_flat_intf (ce_env_t env, ce_appl_exit_t exit, ce_appl_install_t install, ce_appl_flow_block_t flow_block, ce_appl_block_t block, ce_appl_flat_receive_cast_t cast, ce_appl_flat_receive_send_t send, ce_appl_heartbeat_t heartbeat)
LINKDLL void ce_flat_Cast (ce_appl_intf_t *c_appl, ce_len_t len, ce_data_t buf)
LINKDLL void ce_flat_Send (ce_appl_intf_t *c_appl, int num_dests, ce_rank_array_t dests, ce_len_t len, ce_data_t buf)
LINKDLL void ce_flat_Send1 (ce_appl_intf_t *c_appl, ce_rank_t dest, ce_len_t len, ce_data_t buf)


Detailed Description

CE is a C-interface to the Ensemble system. It attempt to provide a simple to use basis from which to build Ensemble applications. To use this interface, one has to read this H file, and link with the ce library --- libce.a on Unix systems, and libce.lib on WIN32.


Define Documentation

#define CE_DEFAULT_PROPERTIES   "Gmp:Sync:Heal:Switch:Frag:Suspect:Flow:Slander"
 

The default set of properties. A stack built with these properties will provide relibale sender-ordered multicast and point-to-point communication, as well as virtual synchrony.

#define CE_DEFAULT_PROTOCOL   "Top:Heal:Switch:Leave:Inter:Intra:Elect:Merge:Slander:Sync:Suspect:Stable:Vsync:Frag_Abv:Top_appl:Frag:Pt2ptw:Mflow:Pt2pt:Mnak:Bottom"
 

The default set of layers.

#define __CE_H__
 

Value:

#define record_clear( rec )   memset(rec, 0, sizeof(*rec))
 

Clear a record.

#define record_create( type, var )   ((type)malloc(sizeof(*var)))
 

Create a record.

#define record_free( rec )   free(rec)
 

Free a record.


Typedef Documentation

typedef int CE_SOCKET
 

CE_Socket allows an os-independent representation for sockets.

typedef ce_addr_t * ce_addr_array_t
 

Arrays of addresses. A null terminated array containing pointers to addresses.

typedef char * ce_addr_t
 

The type of addresses.

typedef void(* ce_appl_block_t)(ce_env_t)
 

Block is called whenever a view change is forthcoming. All applications are blocked, the old view is stabilized, cleaned, and way is made for the new view.

typedef void(* ce_appl_exit_t)(ce_env_t)
 

Exit is called when the member leaves.

typedef void(* ce_appl_flat_receive_cast_t)(ce_env_t, ce_rank_t, ce_len_t, ce_data_t)
 

FlatReceiveCast is called whenever a mulicast message arrives. The received message is NOT owned by the application, it can only be used for read-only operations. It can be assumed to exists for the duration of the callback.

typedef void(* ce_appl_flat_receive_send_t)(ce_env_t, ce_rank_t, ce_len_t, ce_data_t)
 

FlatReceiveSend is called whenever a point-to-point message arrives. The received message is NOT owned by the application, it can only be used for read-only operations. It can be assumed to exists for the duration of the callback.

typedef void(* ce_appl_flow_block_t)(ce_env_t, ce_rank_t, ce_bool_t)
 

FlowBlock is called whenever there are flow-control problems, and the application should refrain from sending messages until further notice.

typedef void(* ce_appl_heartbeat_t)(ce_env_t, ce_time_t)
 

Heartbeat is called every timeout. The timeout is specified in the jops structure.

typedef void(* ce_appl_install_t)(ce_env_t, ce_local_state_t *, ce_view_state_t *)
 

Install is called whenever a new view is installed. Fresh local and view_states are handed to the application, they are hence owned by the application.

typedef struct ce_appl_intf_t ce_appl_intf_t
 

The type of application interface. This is created by the constructor ce_create_intf. There is no need for a destructor because Ensemble frees the interface-structure and all related memory once the Exit callback is called. An application interface is an opaque handle which allows using Ensemble stacks.

typedef void(* ce_appl_receive_cast_t)(ce_env_t, ce_rank_t, int, ce_iovec_array_t)
 

ReceiveCast is called whenever a mulicast message arrives. The iovec array is not owned by the application and should be freed. It can be used for read-only operations, and cannot be assumed to exist after the callback returns.

typedef void(* ce_appl_receive_send_t)(ce_env_t, ce_rank_t, int, ce_iovec_array_t)
 

ReceiveSend is called whenever a point-to-point message arrives. The iovec array is not owned by the application and should be freed. It can be used for read-only operations, and cannot be assumed to exist after the callback returns.

typedef ce_bool_t* ce_bool_array_t
 

typedef int ce_bool_t
 

The type of boolean values.

typedef char * ce_data_t
 

The type of data.

typedef ce_endpt_t * ce_endpt_array_t
 

Arrays of endpoints, these are null terminated arrays of pointers to ce_endpt_t.

typedef char * ce_endpt_t
 

The type of endpoint names. This name does not change throughout an endpoint's life.

typedef void * ce_env_t
 

The type of application environments. An application can set its envrionmet for a specific C-interface, each callback on that C-interface will use this variable.

typedef double ce_float_t
 

The type of floats used here. Should be the same as an ML float.

typedef void(* ce_handler_t)(void *)
 

A handler called when there is input to process on a socket.

typedef ce_iovec_t * ce_iovec_array_t
 

An Io-vector array. ce_iovec_t is defined in mm.h.

typedef struct ce_jops_t ce_jops_t
 

A request structure that describes the list of properties an application wishes from a created endpoint.

typedef int ce_len_t
 

The type of message length, an integer.

typedef struct ce_local_state_t ce_local_state_t
 

The local state describes the group-state pertaining to the local member.

typedef int ce_ltime_t
 

The type of logical time. Used in defining view id's.

typedef ce_rank_t * ce_rank_array_t
 

Arrays of ranks.

typedef int ce_rank_t
 

The type of member ranks, an integer. Each group member is ranked between 0 and (nmembers-1), this allows a very simple addressing scheme.

typedef double ce_time_t
 

The type of time.

typedef ce_view_id_t ** ce_view_id_array_t
 

A null terminated array of pointers view_ids.

typedef struct ce_view_id_t ce_view_id_t
 

The view_id structure describes the logical view id. The basic Ensemble supported abstraction is a group, where members can join and leave dynamically. Each membership change is also called a view change, because it changes the composition of the group. Each view has a view_id which is composed of the group leader, and the logical time. A view_id is unique, and there is a partial order on view_id's.

typedef struct ce_view_state_t ce_view_state_t
 

The view_state describes the current state of the group, it includes the Ensemble version number, the group name, the rank of the coordinator, and more.


Function Documentation

LINKDLL void ce_AddSockRecv ( CE_SOCKET socket,
ce_handler_t handler,
ce_env_t env )
 

This call adds a socket to the list Ensemble listens to. When input on the socket occurs, this handler will be invoked on the specified environment variable.

Parameters:
socket   The socket to listen to.
handler   A handler.
env   An envrionment variable.

LINKDLL void ce_Cast ( ce_appl_intf_t * c_appl,
int num,
ce_iovec_array_t iovl )
 

Send a multicast message to the group.

Parameters:
c_appl   The C-interface.
num   The length of the iovec array.
iovl   an array of io-vectors. The iovl array is consumed.

LINKDLL void ce_ChangeProperties ( ce_appl_intf_t * c_appl,
char * properties )
 

Request a protocol change (specify properties).

Parameters:
c_appl   The C-interface.
properties   a string contaning a colon separated list of properties. For example: "Gmp:Sync:Heal:Switch:Frag:Suspect:Flow:Xfer" The properties string is consumed.

LINKDLL void ce_ChangeProtocol ( ce_appl_intf_t * c_appl,
char * protocol_name )
 

Request a protocol change.

Parameters:
c_appl   The C-interface.
protocol_name   a string describing the new protocol. The string is a colon separated list of layers, for example: "Top:Heal:Switch:Leave: Inter:Intra:Elect:Merge:Sync:Suspect: Stable:Vsync:Frag_Abv:Top_appl: Frag:Pt2ptw:Mflow:Pt2pt:Mnak:Bottom" The protocl_name is consumed.

LINKDLL void ce_Init ( int argc,
char ** argv )
 

Initialize the Ensemble data structures, and process the command line arguments.

The command line arguments are: 1) Those accepted by Ensemble 2) -outboard <mode> In case we're using outboard, which, mode to use: a) FORK: Unix, fork an Ensemble process b) SPAWN: WIN32, spawn an Ensemble process c) TCP: connect to an existing Ensemble daemon through TCP.

LINKDLL void ce_Join ( ce_jops_t * ops,
ce_appl_intf_t * c_appl )
 

Join a group.

Parameters:
ops   A structure describing the join options for this stack. Consumed.
c_appl   An application-interface created earlier.

LINKDLL void ce_Leave ( ce_appl_intf_t * c_appl )
 

Leave a group. After this downcall, the context becomes invalid.

Parameters:
c_appl   The stack that should be closed.

LINKDLL void ce_MLPrintOverride ( void(* handler)(char *msg) )
 

Allows overriding the default ML value printer. For the power-user.

LINKDLL void ce_MLUncaughtException ( void(* handler)(char *info) )
 

Allows overriding the default ML exception handler. For the power-user.

LINKDLL void ce_Main_loop ( void )
 

Transfer control to Ensemble, and start the main loop.

LINKDLL void ce_Prompt ( ce_appl_intf_t * c_appl )
 

Ask for a new View.

Parameters:
c_appl   The C-interface.

LINKDLL void ce_Rekey ( ce_appl_intf_t * c_appl )
 

Ask the system to rekey.

Parameters:
c_appl   The C-interface.

LINKDLL void ce_RmvSockRecv ( CE_SOCKET socket )
 

Remove a socket from the list Ensemble listens to.

Parameters:
socket   The socket to remove.

LINKDLL void ce_Send ( ce_appl_intf_t * c_appl,
int num_dests,
ce_rank_array_t dests,
int num,
ce_iovec_array_t iovl )
 

Send a point-to-point message to a set of group members.

Parameters:
c_appl   The C-interface.
dests   A null terminated sequence of integers.
num_dests   The number of destinations.
num   The length of the iovec array.
iovl   an array of io-vectors. The iovl array is consumed.

LINKDLL void ce_Send1 ( ce_appl_intf_t * c_appl,
ce_rank_t dest,
int num,
ce_iovec_array_t iovl )
 

Send a point-to-point message to the specified group member.

Parameters:
c_appl   The C-interface.
dest   The destination.
num   The length of the iovec array.
iovl   an array of io-vectors. The iovl array is consumed.

LINKDLL void ce_Suspect ( ce_appl_intf_t * c_appl,
int num,
ce_rank_array_t suspects )
 

Report specified group members as failure-suspected.

Parameters:
c_appl   The C-interface.
num   The length of the suspects array
suspects   A list of member ranks. The array is consumed.

LINKDLL void ce_XferDone ( ce_appl_intf_t * c_appl )
 

Inform Ensemble that the state-transfer is complete.

Parameters:
c_appl   The C-interface.

LINKDLL char * ce_copy_string ( char * str )
 

copy a C string.

Parameters:
str   : a C string (ends with '\0')

LINKDLL ce_appl_intf_t * ce_create_flat_intf ( ce_env_t env,
ce_appl_exit_t exit,
ce_appl_install_t install,
ce_appl_flow_block_t flow_block,
ce_appl_block_t block,
ce_appl_flat_receive_cast_t cast,
ce_appl_flat_receive_send_t send,
ce_appl_heartbeat_t heartbeat )
 

Create an application interface using flat callbacks.

LINKDLL ce_appl_intf_t * ce_create_intf ( ce_env_t env,
ce_appl_exit_t exit,
ce_appl_install_t install,
ce_appl_flow_block_t flow_block,
ce_appl_block_t block,
ce_appl_receive_cast_t cast,
ce_appl_receive_send_t send,
ce_appl_heartbeat_t heartbeat )
 

A constructor for application interfaces.

Parameters:
env   The application environemt, includes application specific data. All callbacks on this interface will be made with the variable.
exit   The callback used when the stack is destroyed.
install   The callback performed when a new view is installed.
flow_block   The callback used when flow-control requires the application to block, or unblock. This callback is only a recommendation, it does not actually block or unblock the application.
block   A callback used prior to performing a view change. After block is called, applications cannot send messages, though they may receive them. The application is unblocked * when a new view is installed.
cast   Received a multicast a message.
send   Received a point-to-point message.
heartbeat   A callback performed periodically. The timeout duration is passed to Ensemble in the ce_jops_t structure.
ops   A structure describing the join options for this stack. Consumed.

LINKDLL void ce_flat_Cast ( ce_appl_intf_t * c_appl,
ce_len_t len,
ce_data_t buf )
 

Send a multicast message to the group.

Parameters:
c_appl   The C-interface.
len   The length of the message.
buf   The data to send. The buffer is consumed.

LINKDLL void ce_flat_Send ( ce_appl_intf_t * c_appl,
int num_dests,
ce_rank_array_t dests,
ce_len_t len,
ce_data_t buf )
 

Send a point-to-point message to a set of group members.

Parameters:
c_appl   The C-inteface.
dests   A null terminated sequence of integers.
num_dests   The number of destinations.
len   The length of the message.
buf   The data to send. The buffer is consumed.

LINKDLL void ce_flat_Send1 ( ce_appl_intf_t * c_appl,
ce_rank_t dest,
ce_len_t len,
ce_data_t buf )
 

Send a point-to-point message to the specified group member.

Parameters:
c_appl   The C-inteface.
dest   The destination.
len   The length of the message.
buf   The data to send. The buffer is consumed.

LINKDLL void ce_jops_free ( ce_jops_t * )
 

Free a jops structure.

Parameters:
jops   A join-options structure.

LINKDLL void ce_view_full_free ( ce_local_state_t * ls,
ce_view_state_t * vs )
 

Free a local-state and a view-state.

Parameters:
ls   A local-state structure.
vs   A view-state structure.


Generated at Fri Aug 30 02:15:26 2002 for CE by doxygen1.2.6 written by Dimitri van Heesch, © 1997-2001