-
CONNECTION( |
int fd = BOGUS_FD
,
int port = BOGUS_PORT
,
int idnum = BOGUS_ID
,
SERVICE_GROUP* cgrp = ( ( void* ) 0 )
) ; |
- Method: CONNECTION constructor Summary: Create CONNECTION object to mediate comms on connected socket. Description: After making or accepting a connection, use this to build a CONNECTION object. Arg fd is the file des- criptor of the TCP/IP connection; port is the port number; idnum is an arbitrary int with which to identify this connection, and cgrp points to the SERVICE_GROUP that this obj belongs to (there need not be any). Return: None.
-
- Method: CONNECTION destructor Summary: Destruct the CONNECTION. Description: Returns some allocated storage. Return: None.
-
-
-
-
-
-
-
-
-
-
-
- Read next message from this connection and return thru arg, msg, if able to read whole thing. The returned val indicates the status of the call: WHOLE_MSG_OK : read entire msg; PARTIAL_MSG_OK: read part of msg (rest will be read in subsequent getMsg call(s); NO_MSG_AVAIL : couldn't even get whole internal header (usually means 0 bytes ready at socket so it may indicate a problem if msg expected) CLOSED_CONN : other side has closed the connection.
-
- Blocking version of getMsg:
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Method: outMsgsWaiting_p Summary: Return true if any queued msgs waiting or if there is a partial write pending; otherwise return false. Description: Return true if any queued msgs waiting or if there is a partial write pending; otherwise return false. Return: true or false.
-
- 6/98 NOTE I've created a bunch of new methods whose names begin with "read" or "write" for receiving or sending messages, respectively. These are the new, PREFERRED methods for reading/writing messages and are intended to replace getMsg, getMsg_blk, sendMessage, sendMessage_blk, (which remain for backward compatibility). The main difference is that they return more informative status/error codes (see enum Socket_Status_Code in streamSock.H for status codes).
Basically, what you want to do with a CONNECTION is read or write msgs. Because of the various options available (explained below), there are several permutations: Blocking/Non-blocking: does method stop (block) until read/write completes, or immediately return a result? Copy/NoCopy: (for writing msgs) if we can write only part of your msg, should we copy the remaining portion or just keep a ptr into your msg storage? Buffer Provided/Not: some read methods will allocate buffers with "new char[msgLen]"; alternately, you can pass in a buffer to hold the recvd msg.
-
int readMsgIntoBuff( |
char* permanentMsgBuff
,
int buffLen
,
long* msgBytes
) ; |
- Read msg into user-provided buffer, permanentMsgBuff, return the usual status codes (see readMsg), and set *msgBytes to be #bytes stored in permanentMsgBuff. The provided buffer is called "permanentMsgBuff" because it should be non-stack storage (in case we only get a partial read and have to finish later). Arg buffLen is the size of permanentMsgBuff (in bytes); if the incoming msg is too big, return STREAM_SOCK::USER_BUFF_TOO_SMALL, and set *msgBytes equal to the size of the incoming msg. Then, the user can retrieve this msg by passing in a bigger buffer, or else by calling readMsg (which will allocate a new char[N] buffer). If this returns PARTIAL_MSG_OK, 1 or more additional calls will complete the operation (and return WHOLE_MSG_OK).
-
- Method: readMsgIntoBuff_blk Summary: Read next message (blocking) from connection into user-provided buffer; return status code. Description: Read msg (blocking) into user-provided buffer, permanentMsgBuff, and set *msgBytes to be the number of bytes stored in permanentMsgBuff; return a status code. Arg buffLen is the size of permanentMsgBuff (in bytes); if the incoming msg is too big, return STREAM_SOCK::USER_BUFF_TOO_SMALL, and set *msgBytes equal to the size of the incoming msg. Then, the user can retrieve this msg by passing in a bigger buffer, or else by calling readMsg (which will allocate a new char[N] buffer). If this returns PARTIAL_MSG_OK, do 1 or more additional calls until you've got the entire msg (return == WHOLE_MSG_OK). The provided buffer is called "permanentMsgBuff" because it must remain intact in case there is a partial receive that will be completed later; this means it should NOT be stack storage (unless you're certain you'll complete the read before exiting the function). Return: returns one of the following STREAM_SOCK:: enums (see streamSock.H): WHOLE_MSG_OK : entire msg read; everything is OK USER_BUFF_TOO_SMALL: buffer is too small to hold in- coming msg; redo the call with a bigger buffer or call readMsg (which will allocate one for you). ZERO_BYTES_READ: read 0 bytes; if select says sock is readable but we get 0 bytes, this means that the connection has been closed by the peer. MSG_TOO_BIG: incoming msg bigger than MAX_MSG_BYTES (100 MEG!); probably a mangled msg. TEMP_SOCK_PROBLEM: temporary problem (eg full buffer, interupted call) that _may_ fix itself BAD_SOCK: Bad file descriptor for connection (probably closed conn) BAD_PTR_OR_ARG: Bad msg buff pointer NOT_YET_CONNECTED: Possibly socket is ok, but still doing connection internal work CLOSED_CONN: Connection is closed UNKNOWN_SOCK_ERROR: Don't know what is wrong; better bail out.
-
Method: readMsg_blk
Summary: Block until next msg read from connection; return status
code.
Description: Does a blocking read of the next msg
from the connection into the SockMsgType pointed to
by arg, msg (basically just a char* and #bytes).
Returns a status code indicating what happened.
Will either get the entire message, or else
return an error code.
Return: returns one of the following STREAM_SOCK:: enums
(see streamSock.H):
WHOLE_MSG_OK : entire msg read; everything is OK
MSG_TOO_BIG: incoming msg bigger than MAX_MSG_BYTES
(100 MEG!); probably a mangled msg.
TEMP_SOCK_PROBLEM: temporary problem (eg full buffer,
interupted call) that _may_ fix itself
BAD_SOCK: Bad file descriptor for connection (probably
closed conn)
BAD_PTR_OR_ARG: Bad internal pointer
NOT_YET_CONNECTED: Possibly socket is ok, but still
doing connection internal work
CLOSED_CONN: Connection is closed
UNKNOWN_SOCK_ERROR: Don't know what is wrong; better
bail out.
-
-
-
- Try to complete sending of last partial send. Return true if rest of msg has been sent; false otherwise. Use this fcn repeatedly until entire msg is sent.
-
- Method: resumePartialWrite Summary: Try to finish writing the last message (which resulted in a partial write); return status code. Description: resumePartialWrite attempts to complete the last partial write operation, and returns a status code. A call to this method may itself result in a part- ial send, so it may take more than 1 call to get the whole message out. Since the state of a partial send is recorded internally, no args are needed. Note the asymmetry between the reads and the writes in that there is NO analogous "resumeRead" method. This method was necessary to avoid compli- cations resulting from trying to write a new msg when there is a pending partial write. Return: returns one of the following STREAM_SOCK:: enums (see streamSock.H): WHOLE_MSG_OK : entire msg sent; everything is OK PARTIAL_MSG_OK: part msg sent; everything OK. Complete this operation with calls to resumePartialwrite. TEMP_SOCK_PROBLEM: temporary problem (eg full buffer, interupted call) that _may_ fix itself BAD_SOCK: Bad file descriptor for connection (probably closed connection) BAD_PTR_OR_ARG: Bad pointer or msg length arg NOT_YET_CONNECTED: Possibly socket is ok, but still doing connection internal work CLOSED_CONN: Connection is closed UNKNOWN_SOCK_ERROR: Don't know what is wrong; better quit.
-
Method: resumePartialWrite_blk
Summary: Block until finished writing the last, partially-sent
message; return status code.
Description: resumePartialWrite_blk attempts to complete the last
partial write operation, and returns a status code.
Since the state of a partial
send is recorded internally, no args are needed.
Return: returns one of the following STREAM_SOCK:: enums
(see streamSock.H):
WHOLE_MSG_OK : entire msg sent; everything is OK
TEMP_SOCK_PROBLEM: temporary problem (eg full buffer, interupted
call) that _may_ fix itself
BAD_SOCK: Bad file descriptor for connection (probably closed
connection)
BAD_PTR_OR_ARG: Bad pointer or msg length arg
NOT_YET_CONNECTED: Possibly socket is ok, but still doing
connection internal work
CLOSED_CONN: Connection is closed
UNKNOWN_SOCK_ERROR: Don't know what is wrong; better quit
-
Method: scheduleSend
Summary: Same as scheduleWrite
Description: Old name for scheduleWrite (kept around for back-
wards compatibility).
Return: None
-
- Method: scheduleWrite Summary: Put msg on a queue to be sent out later using method sendQueuedMsgs; if nothing waiting, send immediately. Description: Use this method to queue-up outgoing messages until it is convenient to send them with sendQueuedMsgs. If the queue is empty and there is no pending partial write, just send msg immediately. Queued msgs are COPIED so you may delete msg right after the call. To avoid copying, see scheduleWriteNoCopy. Return: None.
-
- Method: scheduleWriteNoCopy Summary: Put msg on a queue to be sent out later using method sendQueuedMsgs; if nothing waiting, send immediately. Description: Use this method to queue-up outgoing messages until it is convenient to send them with sendQueuedMsgs. If the queue is empty and there is no pending partial write, just send msg immediately. Queued msgs are NOT COPIED so make sure permMsgBuff points to "permanent" storage (ie will not get trashed before sendQueuedMsgs is called). The arg, deleteMsg_p, when true, means that your msg will be deleted when we're done with it (so make sure permMsgBuff was allocated as permMsgBuff = new char[len]). Otherwise, you must delete it yourself. Return: None.
-
Method:
Summary:
Description:
Return:
-
- Blocking version of sendMessage:
-
- Method: sendQueuedMsgs Summary: Finish partial write (if nec) and try to send all queued msgs (non-blocking); return status code. Description: First tries to complete a partial write, if there is one, and then attempts to write all enqueued msgs. Since this is non-blocking, it will return immediately if a resource is blocked (eg full unix buffer), and therefore not necessarily send out all queued msgs. Return: returns one of the following STREAM_SOCK:: enums (see streamSock.H): WHOLE_MSG_OK : entire _queue_ sent; everything is OK PARTIAL_MSG_OK: part of _queue_ sent; everything OK. TEMP_SOCK_PROBLEM: temporary problem (eg full buffer, interupted call) that _may_ fix itself BAD_SOCK: Bad file descriptor for connection (probably closed connection) BAD_PTR_OR_ARG: Bad pointer or msg length arg NOT_YET_CONNECTED: Possibly socket is ok, but still doing connection internal work CLOSED_CONN: Connection is closed UNKNOWN_SOCK_ERROR: Don't know what is wrong; better quit.
-
Method: sendQueuedMsgs_blk
Summary: Finish partial write (if nec) and try to send all queued
msgs (blocking); return status code.
Description: First tries to complete a partial write, if there is
one, and then attempts to write all enqueued msgs.
Since this is non-blocking, it will either
send the entire queue or else return and error
code.
Return: returns one of the following STREAM_SOCK:: enums
(see streamSock.H):
WHOLE_MSG_OK : entire _queue_ sent; everything is OK
TEMP_SOCK_PROBLEM: temporary problem (eg full buffer, interupted
call) that _may_ fix itself
BAD_SOCK: Bad file descriptor for connection (probably closed
connection)
BAD_PTR_OR_ARG: Bad pointer or msg length arg
NOT_YET_CONNECTED: Possibly socket is ok, but still doing
connection internal work
CLOSED_CONN: Connection is closed
UNKNOWN_SOCK_ERROR: Don't know what is wrong; better quit
-
-
-
- Set unix send/recv buffers to max; return 0 if ok.
-
-
-
-
-
-
-
- Set unix internal recv buff; return 0 if ok.
-
- Set unix internal send buff; return 0 if ok.
-
- Method: writeMsg Summary: Send len bytes pointed to by arg, msgBuff, to peer (non-blocking); return status code. Description: Send len bytes pointed to by arg, msgBuff, down connection (non-blocking); return status code. If you get a partial write (returns PARTIAL_MSG_OK), the state of the operation is kept internally and must be completed before beginning another write; call resumePartialwrite 1 or more times to finish a partial write. Return: returns one of the following STREAM_SOCK:: enums (see streamSock.H): WHOLE_MSG_OK : entire msg sent; everything is OK PARTIAL_MSG_OK: part msg sent; everything OK. Complete this operation with calls to resumePartialwrite. TEMP_SOCK_PROBLEM: temporary problem (eg full buffer, interupted call) that _may_ fix itself BAD_SOCK: Bad file descriptor for connection (probably closed connection) BAD_PTR_OR_ARG: Bad pointer or msg length arg NOT_YET_CONNECTED: Possibly socket is ok, but still doing connection internal work CLOSED_CONN: Connection is closed UNKNOWN_SOCK_ERROR: Don't know what is wrong; better quit.
- msg
-
- len
- Method: writeMsgNoCopy Summary: Send len bytes pointed to by arg, permMsgBuff, to peer (non-blocking); return status code. In case of partial write, do NOT copy remainder from permMsgBuff. Description: Send len bytes pointed to by arg, msgBuff, to peer (non-blocking); return status code. If you get a partial write (returns PARTIAL_MSG_OK), the state of the operation is kept internally; in this case we will NOT copy the remaining bytes, but will just keep a pointer into permMsgBuff until the write can be finished (with 1 or more calls to resumePartialWrite), so make sure permMsgBuff points to permanent storage. The arg, deletePermMsg_p, if true, means that this method will delete the storage when done with it using : delete[] (char *) permMsgBuff; So permMsgBuff must be allocated as new char[N] if you want to use this option; otherwise delete it yourself. Return: returns one of the following STREAM_SOCK:: enums (see streamSock.H): WHOLE_MSG_OK : entire msg sent; everything is OK PARTIAL_MSG_OK: part msg sent; everything OK. Complete this operation with calls to resumePartialWrite. TEMP_SOCK_PROBLEM: temporary problem (eg full buffer, interupted call) that _may_ fix itself BAD_SOCK: Bad file descriptor for connection (probably closed connection) BAD_PTR_OR_ARG: Bad pointer or msg length arg NOT_YET_CONNECTED: Possibly socket is ok, but still doing connection internal work CLOSED_CONN: Connection is closed UNKNOWN_SOCK_ERROR: Don't know what is wrong; better quit.
-
int writeMsgNoCopy( |
char* permMsgBuff
,
int len
,
int deletePermMsg_p
) ; |
- Method: writeMsgNoCopy Summary: Send len bytes pointed to by arg, permMsgBuff, to peer (non-blocking); return status code. In case of partial write, do NOT copy remainder from permMsgBuff. Description: Send len bytes pointed to by arg, msgBuff, to peer (non-blocking); return status code. If you get a partial write (returns PARTIAL_MSG_OK), the state of the operation is kept internally; in this case we will NOT copy the remaining bytes, but will just keep a pointer into permMsgBuff until the write can be finished (with 1 or more calls to resumePartialWrite), so make sure permMsgBuff points to permanent storage. The arg, deletePermMsg_p, if true, means that this method will delete the storage when done with it using : delete[] (char *) permMsgBuff; So permMsgBuff must be allocated as new char[N] if you want to use this option; otherwise delete it yourself. Return: returns one of the following STREAM_SOCK:: enums (see streamSock.H): WHOLE_MSG_OK : entire msg sent; everything is OK PARTIAL_MSG_OK: part msg sent; everything OK. Complete this operation with calls to resumePartialWrite. TEMP_SOCK_PROBLEM: temporary problem (eg full buffer, interupted call) that _may_ fix itself BAD_SOCK: Bad file descriptor for connection (probably closed connection) BAD_PTR_OR_ARG: Bad pointer or msg length arg NOT_YET_CONNECTED: Possibly socket is ok, but still doing connection internal work CLOSED_CONN: Connection is closed UNKNOWN_SOCK_ERROR: Don't know what is wrong; better quit.
-
- Method: writeMsgNoCopy_blk Summary: Send len bytes pointed to by arg, permMsgBuff, to peer (blocking); return status code. In case of partial write, do NOT copy remainder from permMsgBuff. Description: Send len bytes pointed to by arg, msgBuff, to peer (non-blocking); return status code. Although a blocking call cannot return a partial write, this can happen internally. In such a case, we will NOT copy the remaining bytes, but will just keep a pointer into permMsgBuff until the write can be finished (with 1 or more calls to resumePartialWrite), so make sure permMsgBuff points to permanent storage. The arg, deletePermMsg_p, if true, means that this method will delete the storage when done with it using : delete[] (char *) permMsgBuff; So permMsgBuff must be allocated as new char[N] if you want to use this option; otherwise delete it yourself. Return: returns one of the following STREAM_SOCK:: enums (see streamSock.H): WHOLE_MSG_OK : entire msg sent; everything is OK TEMP_SOCK_PROBLEM: temporary problem (eg full buffer, interupted call) that _may_ fix itself BAD_SOCK: Bad file descriptor for connection (probably closed connection) BAD_PTR_OR_ARG: Bad pointer or msg length arg NOT_YET_CONNECTED: Possibly socket is ok, but still doing connection internal work CLOSED_CONN: Connection is closed UNKNOWN_SOCK_ERROR: Don't know what is wrong; better quit.
-
Method: writeMsg_blk
Summary: Send len bytes pointed to by arg, msgBuff, to peer
(blocking); return status code.
Description: Send len bytes pointed to by arg, msgBuff, to
peer (blocking); return status code.
Return: returns one of the following STREAM_SOCK:: enums
(see streamSock.H):
WHOLE_MSG_OK : entire msg sent; everything is OK
TEMP_SOCK_PROBLEM: temporary problem (eg full buffer, interupted
call) that _may_ fix itself
BAD_SOCK: Bad file descriptor for connection (probably closed
connection)
BAD_PTR_OR_ARG: Bad pointer or msg length arg
NOT_YET_CONNECTED: Possibly socket is ok, but still doing
connection internal work
CLOSED_CONN: Connection is closed
UNKNOWN_SOCK_ERROR: Don't know what is wrong; better quit
Geb3.98 This class contains the minimum info the server needs to get the msg to the right handler; an application should create its own class that inherits from this one. ServiceType: this specifies the service desired (the server can offer more than one service; see idsOfSrvTypes.H) group: for each service, there can be more than one group of nodes requesting that service (eg 2 simulations, 5 nodes and 8 nodes respectively, asking for comms service, are put in diff groups [we don't want msgs from sim0 going to sim1] handlerNum: # of method that will deal with this message. Bytes: #bytes following the header.
So far a header is just the msg type and length; but this struct enables me to add more later: