C Interface¶
Defines
-
PSI_MSG_MAX
¶ Maximum message size.
-
PSI_MSG_EOF
¶ End of file message.
-
_psiTrackChannels
¶ Maximum number of channels.
-
error
¶
-
debug
¶
-
info
¶
Typedefs
-
typedef struct psiInput_t
psiInput_t
¶ Input queue structure. Contains information on an input queue.
-
typedef struct psiOutput_t
psiOutput_t
¶ Output queue structure. Contains information on an output queue.
-
typedef struct psiRpc_t
psiRpc_t
¶ Remote Procedure Call (RPC) structure. Contains information required to coordinate sending/receiving response/requests from/to an RPC server/client.
Remote Procedure Call (RPC) IO
Handle IO case of a server receiving input from clients, performing some calculation, and then sending a response back to the client.
Server Usage:
- One-time: Create server channels with format specifiers for input and output. psiRpc_t srv = psiRpcServer(“srv_name”, “%d”, “%d %d”);
- Prepare: Allocate space for recovered variables from request. int a;
- Receive request: int ret = rpcRecv(srv, &a);
- Process: Do tasks the server should do with input to produce output. int b = 2*a; int c = 3*a;
- Send response: ret = rpcSend(srv, b, c);
Client Usage:
- One-time: Create client channels to desired server with format specifiers for output and input (should be the same arguments as for the server except for name). psiRpc_t cli = psiRpcClient(“cli_name”, “%d”, “%d %d”);
- Prepare: Allocate space for recovered variables from response. int b, c;
- Call server: int ret = rpcCall(cli, 1, &b, &c);
Clients can also send several requests at once before receiving any responses. This allows the server to be processing the next requests while the client handles the previous response, thereby increasing efficiency. The responses are assumed to be in the same order as the generating requests (i.e. first come, first served).
-
typedef struct psiAsciiFileOutput_t
psiAsciiFileOutput_t
¶ Structure of information for output to a file line by line.
File IO
Handle I/O from/to a local or remote file line by line.
Input Usage:
- One-time: Create file interface by providing either a channel name or a path to a local file. psiAsciiFileInput_t fin = psiAsciiFileInput(“file_channel”, 1); // channel psiAsciiFileInput_t fin = psiAsciiFileInput(“/local/file.txt”, 0); // local file
- Prepare: Allocate space for lines. char line[PSI_MSG_MAX];
- Receive each line, terminating when receive returns -1 (EOF or channel closed). int ret = 1; while (ret > 0) { ret = af_recv_line(fin, line, PSI_MSG_MAX); Do something with the line }
- Cleanup. Call functions to deallocate structures and close files. cleanup_pafi(&fin);
Output Usage:
- One-time: Create file interface by providing either a channel name or a path to a local file. psiAsciiFileOutput_t fout = psiAsciiFileOutput(“file_channel”, 1); // channel psiAsciiFileOutput_t fout = psiAsciiFileOutput(“/local/file.txt”, 0); // local file
- Send lines to the file. If return value is not 0, the send was not succesfull. int ret; ret = af_send_line(fout, “Line 1\n”); ret = af_send_line(fout, “Line 2\n”);
- Send EOF message when done to close the file. ret = af_send_eof(fout);
- Cleanup. Call functions to deallocate structures and close files. cleanup_pafo(&fout);
-
typedef struct psiAsciiFileInput_t
psiAsciiFileInput_t
¶ Structure of information for input from a file line by line.
-
typedef struct psiAsciiTableOutput_t
psiAsciiTableOutput_t
¶ Structure for handling output to an ASCII table.
Table IO
Handle I/O from/to a local or remote ASCII table either line-by-line or as an array.
Row-by-Row
Input by Row Usage:
- One-time: Create file interface by providing either a channel name or a path to a local file. psiAsciiTableInput_t fin = psiAsciiTableInput(“file_channel”, 1); // channel psiAsciiTableInput_t fin = psiAsciiTableInput(“/local/file.txt”, 0); // local table
- Prepare: Allocate space for variables in row (the format in this example is “%5s %d %f\n” like the output example below). char a[5]; int b; double c;
- Receive each row, terminating when receive returns -1 (EOF or channel closed). int ret = 1; while (ret > 0) { ret = at_recv_row(fin, &a, &b, &c); Do something with the row }
- Cleanup. Call functions to deallocate structures and close files. cleanup_pati(&fin);
Output by Row Usage:
- One-time: Create file interface by providing either a channel name or a path to a local file and a format string for rows. psiAsciiTableOutput_t fout = psiAsciiTableOutput(“file_channel”, // channel “%5s %d %f\n”, 1); psiAsciiTableOutput_t fout = psiAsciiTableOutput(“/local/file.txt”, // local table “%5s %d %f\n”, 0);
- Send rows to the file by providing entries. Formatting is handled by the interface. If return value is not 0, the send was not succesful. int ret; ret = at_send_row(fout, “one”, 1, 1.0); ret = at_send_row(fout, “two”, 2, 2.0);
- Send EOF message when done to close the file. ret = at_send_eof(fout);
- Cleanup. Call functions to deallocate structures and close files. cleanup_pato(&fout);
Array
Input by Array Usage:
- One-time: Create file interface by providing either a channel name or a path to a local file. psiAsciiTableInput_t fin = psiAsciiTableInput(“file_channel”, 1); // channel psiAsciiTableInput_t fin = psiAsciiTableInput(“/local/file.txt”, 0); // local table
- Prepare: Declare pointers for table columns (they will be allocated by the interface once the number of rows is known). char *aCol; int *bCol; double *cCol;
- Receive entire table as columns. Return value will be the number of elements in each column (the number of table rows). Negative values indicate errors. int ret = at_recv_array(fin, &a, &b, &c);
- Cleanup. Call functions to deallocate structures and close files. cleanup_pati(&fin);
Output by Array Usage:
- One-time: Create file interface by providing either a channel name or a path to a local file and a format string for rows. psiAsciiTableOutput_t fout = psiAsciiTableOutput(“file_channel”, // channel “%5s %d %f\n”, 1); psiAsciiTableOutput_t fout = psiAsciiTableOutput(“/local/file.txt”, // local table “%5s %d %f\n”, 0);
- Send columns to the file by providing pointers (or arrays). Formatting is handled by the interface. If return value is not 0, the send was not succesful. char aCol[] = {“one ”, “two ”, “three”}; \ Each str is of len 5 int bCol[3] = {1, 2, 3}; float cCol[3] = {1.0, 2.0, 3.0}; int ret = at_send_array(fout, a, b, c);
- Cleanup. Call functions to deallocate structures and close files. cleanup_pato(&fout);
-
typedef struct psiAsciiTableInput_t
psiAsciiTableInput_t
¶ Structure for handling input from an ASCII table.
Functions
-
static void
psiLog
(const char *prefix, const char *fmt, va_list ap)¶ Print a log message. Prints a formatted message, prepending it with the process id and appending it with a newline.
Logging
Alliases are set at compile-time based on the value of PSI_CLIENT_DEBUG. If set to INFO, only messages logged with info or error alias are printed. If set to DEBUG, messages logged with error, info or debug aliases are printed. Otherwise, only error messages are printed. If the PSI_CLIENT_DEBUG is changed, any code including this header must be recompiled for the change to take effect.
- Parameters
prefix
: a constant character pointer to the prefix that should preceed the message and process id.fmt
: a constant character pointer to a format string.ap
: va_list of arguments to be formatted in the format string.
-
static void
psiInfo
(const char *fmt, ...)¶ Print an info log message. Prints a formatted message, prepending it with INFO and the process id. A newline character is added to the end of the message.
- Parameters
fmt
: a constant character pointer to a format string....
: arguments to be formatted in the format string.
-
static void
psiDebug
(const char *fmt, ...)¶ Print an debug log message. Prints a formatted message, prepending it with DEBUG and the process id. A newline character is added to the end of the message.
- Parameters
fmt
: a constant character pointer to a format string....
: arguments to be formatted in the format string.
-
static void
psiError
(const char *fmt, ...)¶ Print an error log message. Prints a formatted message, prepending it with ERROR and the process id. A newline character is added to the end of the message.
- Parameters
fmt
: a constant character pointer to a format string....
: arguments to be formatted in the format string.
-
static int
psi_mq
(char *name, const char *yamlName)¶ Get a sysv_ipc queue identifier based on its name. The queue name is used to locate the queue key stored in the associated environment variable. That key is then used to get the queue ID.
Basic IO
Output Usage:
- One-time: Create output channel (store in named variables) psiOutput_t output_channel = psiOutput(“out_name”);
- Prepare: Format data to a character array buffer. char buffer[PSI_MSG_MAX]; sprintf(buffer, “a=%d, b=%d”, 1, 2);
- Send: ret = psi_send(output_channel, buffer, strlen(buffer));
Input Usage:
- One-time: Create output channel (store in named variables) psiInput_t input_channel = psiInput(“in_name”);
- Prepare: Allocate a character array buffer. char buffer[PSI_MSG_MAX];
- Receive: int ret = psi_recv(input_channel, buffer, PSI_MSG_MAX);
- Return
- int queue identifier.
- Parameters
name
: character pointer to name of environment variable that the queue key should be shored in.yamlName
: constant character pointer to the original name of the queue, absent any suffix. This is used to check if there is an existing queue with that name, but a different suffix.
-
static int
is_eof
(const char *buf)¶ Check if a character array matches the internal EOF message.
- Return
- int 1 if buf is the EOF message, 0 otherwise.
- Parameters
buf
: constant character pointer to string that should be checked.
-
static psiOutput_t
psiOutput
(const char *name)¶ Constructor for psiOutput_t structure. Create a psiOutput_t structure based on a provided name that is used to locate a particular sysv_ipc queue key stored in the environment variable name + “_OUT”.
- Return
- psiOutput_t output queue structure.
- Parameters
name
: constant character pointer to name of queue.
-
static psiInput_t
psiInput
(const char *name)¶ Constructor for psiInput_t structure. Create a psiInput_t structure based on a provided name that is used to locate a particular sysv_ipc queue key stored in the environment variable name + “_IN”.
- Return
- psiInput_t input queue structure.
- Parameters
name
: constant character pointer to name of queue.
-
static psiOutput_t
psi_output
(const char *name)¶ Alias for psiOutput.
-
static psiInput_t
psi_input
(const char *name)¶ Alias for psiInput.
-
static psiOutput_t
psiOutputFmt
(const char *name, char *fmtString)¶ Constructor for psiOutput_t structure with format. Create a psiOutput_t structure based on a provided name that is used to locate a particular sysv_ipc queue key stored in the environment variable name + “_OUT” and a format string that can be used to format arguments into outgoing messages for the queue.
- Return
- psiOutput_t output queue structure.
- Parameters
name
: constant character pointer to name of queue.fmtString
: character pointer to format string.
-
static psiInput_t
psiInputFmt
(const char *name, char *fmtString)¶ Constructor for psiInput_t structure with format. Create a psiInput_t structure based on a provided name that is used to locate a particular sysv_ipc queue key stored in the environment variable name + “_IN” and a format stirng that can be used to extract arguments from messages received from the queue.
- Return
- psiInput_t input queue structure.
- Parameters
name
: constant character pointer to name of queue.fmtString
: character pointer to format string.
-
static int
psi_output_nmsg
(psiOutput_t psiQ)¶ Get the number of messages in an output queue. Check how many messages are waiting in the associated queue for an output queue structure.
- Return
- int number of messages in the queue. -1 if the queue cannot be accessed.
- Parameters
psiQ
: psiOutput_t output queue structure.
-
static int
psi_input_nmsg
(psiInput_t psiQ)¶ Get the number of messages in an input queue. Check how many messages are waiting in the associated queue for an input queue structure.
- Return
- int number of messages in the queue. -1 if the queue cannot be accessed.
- Parameters
psiQ
: psiInput_t input queue structure.
-
static int
psi_send
(psiOutput_t psiQ, char *data, int len)¶ Send a message to an output queue. Send a message smaller than PSI_MSG_MAX bytes to an output queue. If the message is larger, it will not be sent.
- Return
- int 0 if send succesfull, -1 if send unsuccessful.
- Parameters
psiQ
: psiOutput_t structure that queue should be sent to.data
: character pointer to message that should be sent.len
: int length of message to be sent.
-
static int
psi_recv
(psiInput_t psiQ, char *data, int len)¶ Receive a message from an input queue. Receive a message smaller than PSI_MSG_MAX bytes from an input queue.
- Return
- int -1 if message could not be received. Length of the received message if message was received.
- Parameters
psiQ
: psiOutput_t structure that message should be sent to.data
: character pointer to allocated buffer where the message should be saved.len
: int length of the allocated message buffer in bytes.
-
static int
psi_send_nolimit
(psiOutput_t psiQ, char *data, int len)¶ Send a large message to an output queue. Send a message larger than PSI_MSG_MAX bytes to an output queue by breaking it up between several smaller messages and sending initial message with the size of the message that should be expected. Must be partnered with psi_recv_nolimit for communication to make sense.
- Return
- int 0 if send succesfull, -1 if send unsuccessful.
- Parameters
psiQ
: psiOutput_t structure that message should be sent to.data
: character pointer to message that should be sent.len
: int length of message to be sent.
-
static int
psi_recv_nolimit
(psiInput_t psiQ, char **data, int len0)¶ Receive a large message from an input queue. Receive a message larger than PSI_MSG_MAX bytes from an input queue by receiving it in parts. This expects the first message to be the size of the total message.
- Return
- int -1 if message could not be received. Length of the received message if message was received.
- Parameters
psiQ
: psiOutput_t structure that message should be sent to.data
: character pointer to pointer for allocated buffer where the message should be stored. A pointer to a pointer is used so that the buffer may be reallocated as necessary for the incoming message.len0
: int length of the initial allocated message buffer in bytes.
-
static int
vpsiSend
(psiOutput_t psiQ, va_list ap)¶ Send arguments as a small formatted message to an output queue. Use the format string to create a message from the input arguments that is then sent to the specified output queue. If the message is larger than PSI_MSG_MAX or cannot be encoded, it will not be sent.
Formatted IO
Output Usage:
- One-time: Create output channel with format specifier. psiOutput_t output_channel = psiOutputFmt(“out_name”, “a=%d, b=%d”);
- Send: ret = psiSend(output_channel, 1, 2);
Input Usage:
- One-time: Create output channel with format specifier. psiInput_t input_channel = psiInput(“in_name”, “a=%d, b=%d”);
- Prepare: Allocate space for recovered variables. int a, b;
- Receive: int ret = psiRecv(input_channel, &a, &b);
- Return
- int 0 if send succesfull, -1 if send unsuccessful.
- Parameters
psiQ
: psiOutput_t structure that queue should be sent to.ap
: va_list arguments to be formatted into a message using sprintf.
-
static int
vpsiRecv
(psiInput_t psiQ, va_list ap)¶ Assign arguments by receiving and parsing a message from an input queue. Receive a message smaller than PSI_MSG_MAX bytes from an input queue and parse it using the associated format string.
- Return
- int -1 if message could not be received or could not be parsed. Length of the received message if message was received and parsed.
- Parameters
psiQ
: psiOutput_t structure that message should be sent to.ap
: va_list arguments that should be assigned by parsing the received message using sscanf. As these are being assigned, they should be pointers to memory that has already been allocated.
-
static int
psiSend
(psiOutput_t psiQ, ...)¶ Send arguments as a small formatted message to an output queue. Use the format string to create a message from the input arguments that is then sent to the specified output queue. If the message is larger than PSI_MSG_MAX or cannot be encoded, it will not be sent.
- Return
- int 0 if send succesfull, -1 if send unsuccessful.
- Parameters
psiQ
: psiOutput_t structure that queue should be sent to....
: arguments to be formatted into a message using sprintf.
-
static int
psiRecv
(psiInput_t psiQ, ...)¶ Assign arguments by receiving and parsing a message from an input queue. Receive a message smaller than PSI_MSG_MAX bytes from an input queue and parse it using the associated format string.
- Return
- int -1 if message could not be received or could not be parsed. Length of the received message if message was received and parsed.
- Parameters
psiQ
: psiOutput_t structure that message should be sent to....
: arguments that should be assigned by parsing the received message using sscanf. As these are being assigned, they should be pointers to memory that has already been allocated.
-
static int
vpsiSend_nolimit
(psiOutput_t psiQ, va_list ap)¶ Send arguments as a large formatted message to an output queue. Use the format string to create a message from the input arguments that is then sent to the specified output queue. The message can be larger than PSI_MSG_MAX. If it cannot be encoded, it will not be sent.
- Return
- int 0 if formatting and send succesfull, -1 if formatting or send unsuccessful.
- Parameters
psiQ
: psiOutput_t structure that queue should be sent to.ap
: va_list arguments to be formatted into a message using sprintf.
-
static int
vpsiRecv_nolimit
(psiInput_t psiQ, va_list ap)¶ Assign arguments by receiving and parsing a message from an input queue. Receive a message larger than PSI_MSG_MAX bytes in chunks from an input queue and parse it using the associated format string.
- Return
- int -1 if message could not be received or could not be parsed. Length of the received message if message was received and parsed.
- Parameters
psiQ
: psiOutput_t structure that message should be sent to.ap
: va_list arguments that should be assigned by parsing the received message using sscanf. As these are being assigned, they should be pointers to memory that has already been allocated.
-
static int
psiSend_nolimit
(psiOutput_t psiQ, ...)¶ Send arguments as a large formatted message to an output queue. Use the format string to create a message from the input arguments that is then sent to the specified output queue. The message can be larger than PSI_MSG_MAX. If it cannot be encoded, it will not be sent.
- Return
- int 0 if formatting and send succesfull, -1 if formatting or send unsuccessful.
- Parameters
psiQ
: psiOutput_t structure that queue should be sent to....
: arguments to be formatted into a message using sprintf.
-
static int
psiRecv_nolimit
(psiInput_t psiQ, ...)¶ Assign arguments by receiving and parsing a message from an input queue. Receive a message larger than PSI_MSG_MAX bytes in chunks from an input queue and parse it using the associated format string.
- Return
- int -1 if message could not be received or could not be parsed. Length of the received message if message was received and parsed.
- Parameters
psiQ
: psiInput_t structure that message should be sent to....
: arguments that should be assigned by parsing the received message using sscanf. As these are being assigned, they should be pointers to memory that has already been allocated.
-
static psiRpc_t
psiRpc
(const char *outName, char *outFormat, const char *inName, char *inFormat)¶ Constructor for RPC structure. Creates an instance of psiRpc_t with provided information.
- Return
- psiRpc_t structure with provided info.
- Parameters
outName
: constant character pointer name of the output queue.outFormat
: character pointer to format that should be used for formatting output.inName
: constant character pointer to name of the input queue.inFormat
: character pointer to format that should be used for parsing input.
-
static psiRpc_t
psiRpcClient
(const char *name, char *outFormat, char *inFormat)¶ Constructor for client side RPC structure. Creates an instance of psiRpc_t with provided information.
- Return
- psiRpc_t structure with provided info.
- Parameters
name
: constant character pointer to name for queues.outFormat
: character pointer to format that should be used for formatting output.inFormat
: character pointer to format that should be used for parsing input.
-
static psiRpc_t
psiRpcServer
(const char *name, char *inFormat, char *outFormat)¶ Constructor for server side RPC structure. Creates an instance of psiRpc_t with provided information.
- Return
- psiRpc_t structure with provided info.
- Parameters
name
: constant character pointer to name for queues.inFormat
: character pointer to format that should be used for parsing input.outFormat
: character pointer to format that should be used for formatting output.
-
static int
vrpcSend
(psiRpc_t rpc, va_list ap)¶ Format and send a message to an RPC output queue. Format provided arguments list using the output queue format string and then sends it to the output queue under the assumption that it is larger than the maximum message size.
- Return
- integer specifying if the send was succesful. Values >= 0 indicate success.
- Parameters
rpc
: psiRpc_t structure with RPC information.ap
: va_list variable list of arguments for formatting.
-
static int
vrpcRecv
(psiRpc_t rpc, va_list ap)¶ Receive and parse a message from an RPC input queue. Receive a message from the input queue under the assumption that it is larger than the maximum message size. Then parse the message using the input queue format string to extract parameters and assign them to the arguments.
- Return
- integer specifying if the receive was succesful. Values >= 0 indicate success.
- Parameters
rpc
: psiRpc_t structure with RPC information.ap
: va_list variable list of arguments that should be assigned parameters extracted using the format string. Since these will be assigned, they should be pointers to memory that has already been allocated.
-
static int
rpcSend
(psiRpc_t rpc, ...)¶ Format and send a message to an RPC output queue. Format provided arguments using the output queue format string and then sends it to the output queue under the assumption that it is larger than the maximum message size.
- Return
- integer specifying if the send was succesful. Values >= 0 indicate success.
- Parameters
rpc
: psiRpc_t structure with RPC information....
: arguments for formatting.
-
static int
rpcRecv
(psiRpc_t rpc, ...)¶ Receive and parse a message from an RPC input queue. Receive a message from the input queue under the assumption that it is larger than the maximum message size. Then parse the message using the input queue format string to extract parameters and assign them to the arguments.
- Return
- integer specifying if the receive was succesful. Values >= 0 indicate success.
- Parameters
rpc
: psiRpc_t structure with RPC information....
: mixed arguments that should be assigned parameters extracted using the format string. Since these will be assigned, they should be pointers to memory that has already been allocated.
-
static int
vrpcCall
(psiRpc_t rpc, va_list ap)¶ Send request to an RPC server from the client and wait for a response. Format arguments using the output queue format string, send the message to the output queue, receive a response from the input queue, and assign arguments from the message using the input queue format string to parse it.
- Return
- integer specifying if the receive was succesful. Values >= 0 indicate success.
- Parameters
rpc
: psiRpc_t structure with RPC information.ap
: va_list mixed arguments that include those that should be formatted using the output format string, followed by those that should be assigned parameters extracted using the input format string. These that will be assigned should be pointers to memory that has already been allocated.
-
static int
rpcCall
(psiRpc_t rpc, ...)¶ Send request to an RPC server from the client and wait for a response. Format arguments using the output queue format string, send the message to the output queue, receive a response from the input queue, and assign arguments from the message using the input queue format string to parse it.
- Return
- integer specifying if the receive was succesful. Values >= 0 indicate success.
- Parameters
rpc
: psiRpc_t structure with RPC information....
: mixed arguments that include those that should be formatted using the output format string, followed by those that should be assigned parameters extracted using the input format string. These that will be assigned should be pointers to memory that has already been allocated.
-
static psiAsciiFileOutput_t
psiAsciiFileOutput
(const char *name, int dst_type)¶ Constructor for psiAsciiFileOutput_t. Based on the value of dst_type, either a local file will be opened for output (dst_type == 0), or a psiOutput_t connection will be made.
- Return
- psiAsciiFileOutput_t for line-by-line output to a file or channel.
- Parameters
name
: constant character pointer to path of local file or name of an output queue.dst_type
: int 0 if name refers to a local file, 1 if it is a queue.
-
static psiAsciiFileInput_t
psiAsciiFileInput
(const char *name, int src_type)¶ Constructor for psiAsciiFileInput_t. Based on the value of src_type, either a local file will be opened for input (src_type == 0), or a psiInput_t connection will be made.
- Return
- psiAsciiFileInput_t for line-by-line input from a file or channel.
- Parameters
name
: constant character pointer to path of local file or name of an input queue.src_type
: int 0 if name refers to a local file, 1 if it is a queue.
-
static int
af_send_eof
(psiAsciiFileOutput_t t)¶ Send EOF message to output file, closing it.
- Return
- int 0 if send was succesfull. All other values indicate errors.
- Parameters
t
: psiAsciiFileOutput_t output structure.
-
static int
af_recv_line
(psiAsciiFileInput_t t, char *line, size_t n)¶ Receive a single line from an associated file or queue.
- Return
- int Number of bytes read/received. Negative values indicate that there was either an error or the EOF message was received.
- Parameters
t
: psiAsciiFileInput_t input structure.line
: character pointer to allocate memory where the received line should be stored.n
: size_t Size of the allocated memory block in bytes.
-
static int
af_send_line
(psiAsciiFileOutput_t t, char *line)¶ Send a single line to a file or queue.
- Return
- int 0 if send was succesfull. Other values indicate errors.
- Parameters
t
: psiAsciiFileOutput_t output structure.line
: character pointer to line that should be sent.
-
static void
cleanup_pafi
(psiAsciiFileInput_t *t)¶ Deallocate and clean up psiAsciiFileInput_t structure.
- Parameters
t
: psiAsciiFileInput_t pointer.
-
static void
cleanup_pafo
(psiAsciiFileOutput_t *t)¶ Deallocate and clean up psiAsciiFileOutput_t structure.
- Parameters
t
: psiAsciiFileOutput_t pointer.
-
static psiAsciiTableOutput_t
psiAsciiTableOutput
(const char *name, char *format_str, int dst_type)¶ Constructor for psiAsciiTableOutput_t.
- Return
- psiAsciiTableOutput_t output structure.
- Parameters
name
: constant character pointer to local file path or message queue name.format_str
: character pointer to format string that should be used to format rows into table lines.dst_type
: int 0 if name is a local file path, 1 if it is the name of a message queue.
-
static psiAsciiTableInput_t
psiAsciiTableInput
(const char *name, int src_type)¶ Constructor for psiAsciiTableInput_t.
- Return
- psiAsciiTableInput_t input structure.
- Parameters
name
: constant character pointer to local file path or message queue name.src_type
: int 0 if name is a local file path, 1 if it is the name of a message queue.
-
static int
at_psi_send
(psiAsciiTableOutput_t t, char *data, int len)¶ Send a nolimit message to a table output queue.
- Return
- int 0 if send succesfull, -1 if send unsuccessful.
- Parameters
t
: psiAsciiTableOutput_t output structure.data
: character pointer to message that should be sent.len
: int length of message to be sent.
-
static int
at_psi_recv
(psiAsciiTableInput_t t, char **data, int len)¶ Recv a nolimit message from a table input queue.
- Return
- int -1 if message could not be received. Length of the received message if message was received.
- Parameters
t
: psiAsciiTableInput_t input structure.data
: character pointer to pointer to memory where received message should be stored. It does not need to be allocated, only defined.len
: int length of allocated buffer.
-
static int
at_send_eof
(psiAsciiTableOutput_t t)¶ Send a nolimit EOF message to a table output queue.
- Return
- int 0 if send succesfull, -1 if send unsuccessful.
- Parameters
t
: psiAsciiTableOutput_t output structure.
-
static int
vsend_row
(psiAsciiTableOutput_t t, va_list ap)¶ Format and send a row to the table file/queue.
- Return
- int 0 if send succesfull, -1 if send unsuccessful.
- Parameters
t
: psiAsciiTableOutput_t output structure.ap
: va_list Row elements that should be formatted.
-
static int
vrecv_row
(psiAsciiTableInput_t t, va_list ap)¶ Recv and parse a row from the table file/queue.
- Return
- int -1 if message could not be received or parsed, otherwise the length of the received is returned.
- Parameters
t
: psiAsciiTableInput_t input structure.ap
: va_list Pointers to memory where variables from the parsed should be stored.
-
static int
at_send_row
(psiAsciiTableOutput_t t, ...)¶ Format and send a row to the table file/queue.
- Return
- int 0 if send succesfull, -1 if send unsuccessful.
- Parameters
t
: psiAsciiTableOutput_t output structure....
: Row elements that should be formatted.
-
static int
at_recv_row
(psiAsciiTableInput_t t, ...)¶ Recv and parse a row from the table file/queue.
- Return
- int -1 if message could not be received or parsed, otherwise the length of the received is returned.
- Parameters
t
: psiAsciiTableInput_t input structure....
: Pointers to memory where variables from the parsed row should be stored.
-
static int
vsend_array
(psiAsciiTableOutput_t t, int nrows, va_list ap)¶ Format and send table columns to the table file/queue.
- Return
- int 0 if send succesfull, -1 if send unsuccessful.
- Parameters
t
: psiAsciiTableOutput_t output structure.nrows
: int Number of rows in the columns.ap
: va_list Pointers to memory containing table columns that should be formatted.
-
static int
vrecv_array
(psiAsciiTableInput_t t, va_list ap)¶ Recv and parse columns from a table file/queue.
- Return
- int Number of rows received. Negative values indicate errors.
- Parameters
t
: psiAsciiTableInput_t input structure.ap
: va_list Pointers to pointers to memory where columns from the parsed table should be stored. They need not be allocated, only declared.
-
static int
at_send_array
(psiAsciiTableOutput_t t, int nrows, ...)¶ Format and send table columns to the table file/queue.
- Return
- int 0 if send succesfull, -1 if send unsuccessful.
- Parameters
t
: psiAsciiTableOutput_t output structure.nrows
: int Number of rows in the columns....
: Pointers to memory containing table columns that should be formatted.
-
static int
at_recv_array
(psiAsciiTableInput_t t, ...)¶ Recv and parse columns from a table file/queue.
- Return
- int Number of rows received. Negative values indicate errors.
- Parameters
t
: psiAsciiTableInput_t input structure....
: Pointers to pointers to memory where columns from the parsed table should be stored. They need not be allocated, only declared.
-
static void
cleanup_pati
(psiAsciiTableInput_t *t)¶ Deallocate and clean up psiAsciiTableInput_t structure.
- Parameters
t
: psiAsciiTableInput_t pointer.
-
static void
cleanup_pato
(psiAsciiTableOutput_t *t)¶ Deallocate and clean up psiAsciiTableOutput_t structure.
- Parameters
t
: psiAsciiTableOutput_t pointer.
Variables
-
char *
_psiChannelNames
[_psiTrackChannels]¶ Names of channels in use.
-
unsigned
_psiChannelsUsed
= 0¶ Number of channels in use.
-
struct
msgbuf_t
¶ - #include <PsiInterface.h>
Message buffer structure.
-
struct
psiInput_t
¶ - #include <PsiInterface.h>
Input queue structure. Contains information on an input queue.
-
struct
psiOutput_t
¶ - #include <PsiInterface.h>
Output queue structure. Contains information on an output queue.
-
struct
psiRpc_t
¶ - #include <PsiInterface.h>
Remote Procedure Call (RPC) structure. Contains information required to coordinate sending/receiving response/requests from/to an RPC server/client.
Remote Procedure Call (RPC) IO
Handle IO case of a server receiving input from clients, performing some calculation, and then sending a response back to the client.
Server Usage:
- One-time: Create server channels with format specifiers for input and output. psiRpc_t srv = psiRpcServer(“srv_name”, “%d”, “%d %d”);
- Prepare: Allocate space for recovered variables from request. int a;
- Receive request: int ret = rpcRecv(srv, &a);
- Process: Do tasks the server should do with input to produce output. int b = 2*a; int c = 3*a;
- Send response: ret = rpcSend(srv, b, c);
Client Usage:
- One-time: Create client channels to desired server with format specifiers for output and input (should be the same arguments as for the server except for name). psiRpc_t cli = psiRpcClient(“cli_name”, “%d”, “%d %d”);
- Prepare: Allocate space for recovered variables from response. int b, c;
- Call server: int ret = rpcCall(cli, 1, &b, &c);
Clients can also send several requests at once before receiving any responses. This allows the server to be processing the next requests while the client handles the previous response, thereby increasing efficiency. The responses are assumed to be in the same order as the generating requests (i.e. first come, first served).
Public Members
-
psiInput_t
_input
¶ Input queue structure.
-
psiOutput_t
_output
¶ Output queue structure.
-
char *
_inFmt
¶ Format string used for input queue.
-
char *
_outFmt
¶ Format string used for output queue.
-
struct
psiAsciiFileOutput_t
¶ - #include <PsiInterface.h>
Structure of information for output to a file line by line.
File IO
Handle I/O from/to a local or remote file line by line.
Input Usage:
- One-time: Create file interface by providing either a channel name or a path to a local file. psiAsciiFileInput_t fin = psiAsciiFileInput(“file_channel”, 1); // channel psiAsciiFileInput_t fin = psiAsciiFileInput(“/local/file.txt”, 0); // local file
- Prepare: Allocate space for lines. char line[PSI_MSG_MAX];
- Receive each line, terminating when receive returns -1 (EOF or channel closed). int ret = 1; while (ret > 0) { ret = af_recv_line(fin, line, PSI_MSG_MAX); Do something with the line }
- Cleanup. Call functions to deallocate structures and close files. cleanup_pafi(&fin);
Output Usage:
- One-time: Create file interface by providing either a channel name or a path to a local file. psiAsciiFileOutput_t fout = psiAsciiFileOutput(“file_channel”, 1); // channel psiAsciiFileOutput_t fout = psiAsciiFileOutput(“/local/file.txt”, 0); // local file
- Send lines to the file. If return value is not 0, the send was not succesfull. int ret; ret = af_send_line(fout, “Line 1\n”); ret = af_send_line(fout, “Line 2\n”);
- Send EOF message when done to close the file. ret = af_send_eof(fout);
- Cleanup. Call functions to deallocate structures and close files. cleanup_pafo(&fout);
Public Members
-
int
_valid
¶ Indicates if the structure was succesfully initialized.
-
const char *
_name
¶ Path to local file or name of output channel.
-
int
_type
¶ 0 for local file, 1 for output channel.
-
asciiFile_t
_file
¶ Associated output handler for local files.
-
psiOutput_t
_psi
¶ Associated output handler for output channel.
-
struct
psiAsciiFileInput_t
¶ - #include <PsiInterface.h>
Structure of information for input from a file line by line.
Public Members
-
int
_valid
¶ Indicates if the structure was succesfully initialized.
-
const char *
_name
¶ Path to local file or name of input channel.
-
int
_type
¶ 0 for local file, 1 for input channel.
-
asciiFile_t
_file
¶ Associated input handler for local files.
-
psiInput_t
_psi
¶ Associated input handler for input channel.
-
int
-
struct
psiAsciiTableOutput_t
¶ - #include <PsiInterface.h>
Structure for handling output to an ASCII table.
Table IO
Handle I/O from/to a local or remote ASCII table either line-by-line or as an array.
Row-by-Row
Input by Row Usage:
- One-time: Create file interface by providing either a channel name or a path to a local file. psiAsciiTableInput_t fin = psiAsciiTableInput(“file_channel”, 1); // channel psiAsciiTableInput_t fin = psiAsciiTableInput(“/local/file.txt”, 0); // local table
- Prepare: Allocate space for variables in row (the format in this example is “%5s %d %f\n” like the output example below). char a[5]; int b; double c;
- Receive each row, terminating when receive returns -1 (EOF or channel closed). int ret = 1; while (ret > 0) { ret = at_recv_row(fin, &a, &b, &c); Do something with the row }
- Cleanup. Call functions to deallocate structures and close files. cleanup_pati(&fin);
Output by Row Usage:
- One-time: Create file interface by providing either a channel name or a path to a local file and a format string for rows. psiAsciiTableOutput_t fout = psiAsciiTableOutput(“file_channel”, // channel “%5s %d %f\n”, 1); psiAsciiTableOutput_t fout = psiAsciiTableOutput(“/local/file.txt”, // local table “%5s %d %f\n”, 0);
- Send rows to the file by providing entries. Formatting is handled by the interface. If return value is not 0, the send was not succesful. int ret; ret = at_send_row(fout, “one”, 1, 1.0); ret = at_send_row(fout, “two”, 2, 2.0);
- Send EOF message when done to close the file. ret = at_send_eof(fout);
- Cleanup. Call functions to deallocate structures and close files. cleanup_pato(&fout);
Array
Input by Array Usage:
- One-time: Create file interface by providing either a channel name or a path to a local file. psiAsciiTableInput_t fin = psiAsciiTableInput(“file_channel”, 1); // channel psiAsciiTableInput_t fin = psiAsciiTableInput(“/local/file.txt”, 0); // local table
- Prepare: Declare pointers for table columns (they will be allocated by the interface once the number of rows is known). char *aCol; int *bCol; double *cCol;
- Receive entire table as columns. Return value will be the number of elements in each column (the number of table rows). Negative values indicate errors. int ret = at_recv_array(fin, &a, &b, &c);
- Cleanup. Call functions to deallocate structures and close files. cleanup_pati(&fin);
Output by Array Usage:
- One-time: Create file interface by providing either a channel name or a path to a local file and a format string for rows. psiAsciiTableOutput_t fout = psiAsciiTableOutput(“file_channel”, // channel “%5s %d %f\n”, 1); psiAsciiTableOutput_t fout = psiAsciiTableOutput(“/local/file.txt”, // local table “%5s %d %f\n”, 0);
- Send columns to the file by providing pointers (or arrays). Formatting is handled by the interface. If return value is not 0, the send was not succesful. char aCol[] = {“one ”, “two ”, “three”}; \ Each str is of len 5 int bCol[3] = {1, 2, 3}; float cCol[3] = {1.0, 2.0, 3.0}; int ret = at_send_array(fout, a, b, c);
- Cleanup. Call functions to deallocate structures and close files. cleanup_pato(&fout);
Public Members
-
int
_valid
¶ Success or failure of initializing the structure.
-
const char *
_name
¶ Path to local table or name of message queue.
-
asciiTable_t
_table
¶ Associated output handler for local tables.
-
psiOutput_t
_psi
¶ Associated output handler for queues.
-
struct
psiAsciiTableInput_t
¶ - #include <PsiInterface.h>
Structure for handling input from an ASCII table.
Public Members
-
int
_valid
¶ Success or failure of initializing the structure.
-
const char *
_name
¶ Path to local table or name of message queue.
-
asciiTable_t
_table
¶ Associated input handler for local tables.
-
psiInput_t
_psi
¶ Associated input handler for queues.
-
int