| .\"Copyright 2008-2010 IBM Corp. |
| .TH SCI_Initialize 3 "Dec 4, 2009" "1.0.0" "SCI" |
| |
| .SH NAME |
| \fBSCI_Initialize\fP \- Initializes the SCI execution environment |
| |
| .SH SYNTAX |
| .ft R |
| |
| .SH C Syntax |
| .nf |
| #include <sci.h> |
| int SCI_Initialize(sci_info_t *\fIinfo\fP) |
| |
| .SH INPUT PARAMETERS |
| .ft R |
| .TP 1i |
| info |
| Pointer to the SCI startup information (IN). |
| |
| .SH DESCRIPTION |
| .ft R |
| This routine must be called before any other SCI routines are called. |
| SCI can be initialized more than once; subsequent calls to SCI_Initialize |
| are erroneous unless SCI_Terminate be called. |
| .sp |
| All SCI programs must contain a call to SCI_Initialize. SCI_Initialize |
| accepts \fIinfo\fP as its argument: |
| .sp |
| .nf |
| typedef union { |
| sci_end_type_t type; |
| sci_fe_info_t fe_info; |
| sci_be_info_t be_info; |
| } sci_info_t; |
| .fi |
| .sp |
| \fItype\fP can be \fBSCI_FRONT_END\fP or \fBSCI_BACK_END\fP. |
| .sp |
| In \fIsci_fe_info_t\fP: |
| .sp |
| .nf |
| typedef struct { |
| sci_end_type_t type; |
| sci_mode_t mode; |
| SCI_msg_hndlr *hndlr; |
| void *param; |
| SCI_err_hndlr *err_hndlr; |
| char *hostfile; |
| char *bepath; |
| char **beenvp; |
| char reserve[64]; |
| } sci_fe_info_t; |
| .fi |
| .sp |
| \fImode\fP indicates the working mode of the front end, can be interrupt mode |
| (\fBSCI_INTERRUPT\fP) or polling mode (\fBSCI_POLLING\fP), \fIhndlr\fP specified |
| the message handler and it can't be \fBNULL\fP, \fIparam\fP specifies user-defined |
| parameter in the message handler, \fIerr_hndlr\fP specifies the error handler when |
| errors occur and it can be \fBNULL\fP, \fIhostfile\fP specifies the host list to initialize |
| back ends, \fIbepath\fP specifies the command to run a back end, \fIbeenvp\fP specifies |
| any additional environment variables user wants to pass to back ends and it should |
| be ended with a \fBNULL\fP sign. |
| .sp |
| In \fIsci_be_info_t\fP: |
| .sp |
| .nf |
| typedef struct { |
| sci_end_type_t type; |
| sci_mode_t mode; |
| SCI_msg_hndlr *hndlr; |
| void *param; |
| SCI_err_hndlr *err_hndlr; |
| char reserve[64]; |
| } sci_be_info_t; |
| .fi |
| .sp |
| \fImode\fP indicates the working mode of the front end, can be interrupt mode |
| (\fBSCI_INTERRUPT\fP) or polling mode (\fBSCI_POLLING\fP), \fIhndlr\fP specified |
| the message handler and it can't be \fBNULL\fP, \fIparam\fP specifies user-defined |
| parameter in the message handler, \fIerr_hndlr\fP specifies the error handler when |
| errors occur and it can be \fBNULL\fP. |
| .sp |
| Each program can be started as a front end or a back end, and can |
| work in polling mode or interrupt mode, furthermore, besides sci_info_t, |
| the following environment variables begin with the prefix "SCI_" can be |
| used to tune SCI programs (if a data field in sci_info_t indicates the same |
| attribute as an environment variable, it will be overwritten): |
| .sp |
| .TP 1i |
| SCI_HOST_FILE |
| host file, same as fe_info.hostfile in sci_info_t |
| .TP 1i |
| SCI_BACKEND_NUM |
| number of back ends when startup |
| .TP 1i |
| SCI_DEBUG_FANOUT |
| fanout of the SCI tree structure, the default value is 32 |
| .TP 1i |
| SCI_BACKEND_PATH |
| command to start a back end, same as fe_info.bepath in sci_info_t, can contain |
| arguments, e.g., "/usr/bin/pdb_be 2" |
| .TP 1i |
| SCI_USE_EXTLAUNCHER |
| set to "yes" to indicate all back ends are started by an external launcher, the |
| default value is "no" |
| .TP 1i |
| SCI_ENABLE_FAILOVER |
| set to "yes" to indicate SCI will try to recover connections when facing connection |
| problems, the default value is "no" |
| .TP 1i |
| SCI_REMOTE_SHELL |
| can be "rsh", "ssh" or "", indicates how underlying SCI processes (agents, back ends) |
| will be started, "rsh" means using rshell, "ssh" means using ssh, "" means using sci |
| daemon, it's the default value |
| .TP 1i |
| SCI_DEVICE_NAME |
| can be "" or an ifconfig interface name, e.g., "ib0", if set to "", the connection path |
| indicated by the first interface will be used, otherwise the specified connection path |
| will be used, the default value is the first ifconfig device name |
| .TP 1i |
| SCI_SEGMENT_SIZE |
| message segment size used in SCI pipeline mechanism, when the size of downstream |
| messages exceed a threshold (1.5 * size), this mechanism will be enabled |
| automatically by splitting the large message into smaller segments to |
| increase the overall bandwidth, the default size is 46720 (bytes) |
| .TP 1i |
| SCI_SYNC_INIT |
| if set to yes, the SCI_Initilize will block until all the backends are launched, |
| otherwise it will return immediately. The default value is no. |
| .TP 0i |
| .sp |
| For more information, please refer to SCI's online documents. |
| |
| .SH EXAMPLE |
| .ft R |
| .nf |
| void handler(void *user_param, sci_group_t group, void *buffer, int size) |
| { |
| ... |
| } |
| |
| { |
| sci_info_t info; |
| info.type = SCI_FRONT_END; |
| info.fe_info.mode = SCI_INTERRUPT; |
| info.fe_info.hostfile = "./host.list"; |
| info.fe_info.bepath = "/usr/bin/pdb_be"; |
| info.fe_info.hndlr = (SCI_msg_hndlr *)&handler; |
| info.fe_info.param = NULL; |
| SCI_Initialize(&info); |
| ... |
| SCI_Terminate(); |
| } |
| .fi |
| |
| .SH ERRORS |
| .ft R |
| All SCI routines return an error value. |
| .sp |
| .TP 1i |
| SCI_ERR_INVALID_ENDTYPE |
| Invalid end type, can only be SCI_FRONT_END or SCI_BACK_END |
| .TP 1i |
| SCI_ERR_NO_MEM |
| Out of memory |
| .TP 1i |
| SCI_ERR_INVALID_JOBKEY |
| Invalid job key specified by SCI_JOB_KEY (only for BE) |
| .TP 1i |
| SCI_ERR_INVALID_HOSTFILE |
| Invalid host file (only for FE) |
| .TP 1i |
| SCI_ERR_UNKNOWN_INFO |
| Unknown back end info (only for FE) |
| .TP 1i |
| SCI_ERR_LAUNCH_FAILED |
| Failed to launch client(s) (only for FE) |
| .TP 1i |
| SCI_ERR_INITIALIZE_FAILED |
| Initialization failed |
| |
| .SH SEE ALSO |
| .ft R |
| .nf |
| \fBSCI_Terminate\fP(3) |
