Infrasctucture Io Function Reference

Io
The IO system uses an integer handle to reference an existing virtual circuit and character pointers to reference messages.    There is a single input queue for all inbound messages with action type EVTDRVR, the normal application message type.    Each virtual circuit has it's own output queue and input queue for messages in transit.
LAW OF CONSERVATION OF MESSAGE SPACE: A message may be created either my directly calling ioMkMsg() or ioMkRsp() or by receiving a message (ioRcv()).    When a message is sent (transmitted) it's space if freed.    A received message must be freed or re-sent.    If you send a message you have received, without modifying it's virtual circuit, the message returns to it's origin.
The I/O system is an event driven system, that is, when a message arrives it's action type is used as the event type and all events registered to that action code are fired.    The default action for application messages is EVTDRVR.
Different events can be used for communication between any two parts of a system. This communication is invisible to the application, but no messages can be received or sent if the process doesn't call ioWait().
A description of the protocol API is forthcomming and will describe how to add a new protocol to the Io system.

devDo     devReq     ioAddCfg     ioAddProtocol     ioClose     ioCloseAll    
ioClrWatOut     ioDoEvent     ioFree     ioFwdDst     ioFwdId     ioGetCfg    
ioGetMsgId     ioGetMsgLen     ioGetPath     ioGetHndl     ioGetPeer     ioInit    
ioMakMsg     ioMakRsp     ioNew     ioOutBusy     ioOpen     ioPing    
ioPingAsync     ioRcv     ioRegEvent     ioRegWat     ioSetWatOut     ioWait    
ioWaitUs     mInit     mLck     mUnLck    

int  devDo( int devId )
Perform all delayed events with the specified "devId"    If the "devId" is zero, perform all delayed events.    There are currently 30 Delayed Event Ids defined as "Dev1" through "Dev30".    Delayed events are volatile, that is, they only occurr once after each registration.    A delayed event call-back can request another delayed event of the same ID but it won't happen until the next devDo().
Delayed Events are really handy to use inside a signal handler so the time in the handler is minimized.    In this case, you should call devDo in the main line or when you get around to it.

int  devReq( int devId, pfi_t func, void* conTxt )
Request a delayed event.    There are currently 30 Delayed Event Ids defined as "Dev1" through "Dev30".    The "devId" determines who or when it will be executed.    The "func" to be called at "do" time, and "conTxt" to be passed to the called function.    The call back func's prototype.
         int callBack( void *conTxt );
Delayed events are volatile, that is, they only occurr once after each registration.    A delayed event call-back can request another delayed event of the same ID but it won't happen until the next devDo().
Delayed Events are really handy to use inside a signal handler so the time in the handler is minimized.    In this case, you should call devDo in the main line or when you get around to it.

int  ioAddCfg( int proto, char* name, char* loc, char* phy, char* enc, char* key )
Add a port configuration the the local process's IO system. A typical call: ioAddCfg( TCP, "MyCmdQue", "Barf", "4201", "Blowfish", "how now brindle bovine" ); Would add a port (or destination) named "MyCmdQue" on the external IP of host "Barf", at port 4201, encrypted using the Blowfish algorythm, and an encryption key of "how now brindle bovine". If "enc" and "key" are not needed, they should be NULL. If "loc" is "*" or "localhost" the local host loop back is used.

int  ioAddProtocol( int protocol, char* name, pfi_t init )
Add a protocol to the local hosts IO capabilities. This is used by ioInit to install the TCP protocol, and has been used in the past to install HTTP (a character based socket protocol), TTY (single character keyboard ptotocol), and other protocols. The argument "protocol" must not be the same as TCP, "name" is it's label (like "TCP") and "init" points to an initialization function which will be passed a newly created protocol control block which it must fill in with such things as input, output, and exception handler function pointers.

int  ioClose( int sd )
Close a socket "sd" and it's connection control.

int  ioCloseAll( )
Close all sockets. Used by sys.c after forking a new sub-process and before exec. This prevents the new process from being encumbered (inheriting) a raft of opens sockets which may be connected to no telling where.

int  ioClrWatOut( int sd )
This clears the wait on output flag for sd in the master wait list.

int  ioDoEvent( int type, void* option )
Execute an event of type "type".    All handlers (call-backs) registered to this event will be called and passed both the "context" which was established at registeration time and the ioDoEvents "option" arguments.
CALL-BACK FUNCTION: int ioEvent( void *registeredContext, void *option)   

int  ioFree( char* msg )
Free a message created by the IO system either by ioMakMsg() or ioRcv().

int  ioFwdDst( char* msg, char* dest, int len )
Forward an existing message pointed to by "msg", to destination named "dest". The message is of length "len". The message may have originally been created with a much greater length than was actually needed, so "len" indicates the number of bytes to actually transmit. Returns OK if all went well, else ERR. As in all IO send operations, the message space is free after transmission.

int  ioFwdId( char* msg, int handle )
Simular to ioFwdDst() above but it sends the message across an already existing virtual circuit indicated by "handle". The handle may be acquired by using ioGetHndl( msg* ) or by ioGetPath( dest* ).

int  ioGetCfg( char* out, char* name )
Get IO configured ports. If "out" points to a NULL string, ioGetCfg goes to the beginning of it's config chain, else it goes to the next entry. The output looks like: PROTO LogicalName Location PhysicalName [EncryptionMeth Key] This is the same information as required by ioAddCfg() above.

int  ioGetMsgId( char* msg )
Returns the Socket IF of the messages.

int  ioGetMsgLen( char* msg )
Returns the byte count of the message pointed to by "msg".

int  ioGetPath( char* queName )
Returns an IO message handle which may be used to create a message or send an existing message. This call looks in it's port chain then it's config chain for a defined queue, then conects to the queue and sends/receives an IO "ping" message. If all went well an IO handle is returned else ERR.

int  ioGetHndl( char* msg )
Get the handle associated with the message pointed to by "msg".

char*  ioGetPeer( char* mp )
Return the logical name of the peer process.

int  ioInit( int argc, char** argv )
Initialize the IO system (called from infInit()). Returns argc.

char*  ioMakMsg( int handle, int len )
Create an IO messages of length "len" and associated with IO handle (virtual circuit) "handle".

char*  ioMakRsp( char* msg, int length )
Create a response message to the existing message pointed to by "msg", and of length "len".

char*  ioNew( char* name, int len )
Create a new message destined for "name" queue and of length "len". Returns a pointer to a new IO message.

int  ioOutBusy( int handle )
Returns TRUE if the output queue is not empty, else FALSE if it is. This is used by some processes before exiting to see if their last message has been transmitted.

int  ioOpen( char* name )
Open a server queue and begin listening for connection requests.

int  ioPing( int hndl, char* msg )
Pings are intended to connect or test a virtual circuit and incidentally excahange information about processes.    Send an IO ping message across the circuit refereneced by "handle" then wait for a response.    The ascii string int the buffer pointed to by "msg" will be appended to the ping and buffer will be used to receive the response message.    The receiving process may access the entire ping message by registering a function associated with the event EVTPING.    The caller will get the entire ping response message in it's buffer pointed to by "msg".    The ping message format is: "hostName,procName,PingSeq#,PeerPid,callerMsg"    NOTE: Two events are used "under the covers" to implement ping, EVTPING1 (the request) and EVTPING2 (the reponse).

int  ioPingAsync( int hndl, char* msg )
Pings are intended to connect or test a virtual circuit and incidentally excahange information about processes.    The asynchronous ping may also be used as a keep alive or stall alarm.    Send an IO ping message across the circuit refereneced by "handle".    The ascii string pointed to by "msg" will be appended to the ping message and then be transmitted to the connection peer process.    If the transmitt was successful, the call returns OK immediately after transmitting the "Ping" request.    If a transmitt error occurred, ERR is returned.    The receiving process may access the entire ping message by registering a function associated with the event EVTPING.    The originating process may see any return message (and determine if the ping was successful) by registering a call-back to event PINGECHO.    The ping message format is: "hostName,procName,PingSeq#,PeerPid,callerMsg"    NOTE: Two events are used "under the covers" to implement ping, EVTPING1 (the request) and EVTPING2 (the reponse).   

char*  ioRcv( )
Receive an IO message.    Returns a message pointer if one is available and NULL if not.

int  ioRegEvent( int eventType, pfi_t cbFunc, void* context )
Register an event of type "eventType".    When this event occurs the function "cbFunc" will be called and passed this "context" and the ioDoEvent "option" as arguments.
CALL-BACK FUNCTION: int ioEvent( void *registeredContext, void *option)

int  ioRegWat( int sd, pfi_t inputCbFunc, pfi_t outputCbFunc, pfi_t exceptionCbFunc, void* contxt )
Register an I/O socket descriptor's callbacks.    The "inputCbFunc" is for input interrupts, the "outputCbFunc" is for output interrupts, and the "exceptionCbFunc" is for exceptions.    The "contxt" variable is provided to all three call-backs.
CALL-BACK FUNCTION: int call-back( void *contxt)

int  ioSetWatOut( int sd )
This sets the wait on output flag for sd in the master wait list.

int  ioWait( int timeout )
Wait for "timeout" milliseconds or until an event transpires which returns OK.    Returns OK if an event retuned one else NULL for timeout.    This macro calls ioWaitUs()

int  ioWaitUs( int timeout )
This is the low level ioWait waits for microseconds.

int  mInit( void* mutexPtr )
Initialize the mutex pointed to by "mutexPtr".    Return OK.

int  mLck( void* mutexPtr )
Lock the mutex pointed to by "mutexPtr".    Return OK.

int  mUnLck( void* mutexPtr )
Unlock the mutex pointed to by "mutexPtr".    Return OK.