8. System - MachInfo, PTask, Timer, VSocket

These modules provide interfaces to computer system services and information. The MachInfo module can be queried for certain machine hardware information such as the number of processors or total amount of physical memory. The PTask module is designed for managing threads in a multithreaded application. The Timer module can be used to accumulate user and system time for any number of sections of application software. This is useful for performance tuning. The VSocket module can be used to instance master and client sockets that can communicate with each other through a defined port number across homogeneous or non-homogeneous networks.

8.1. Machine Information - MachInfo

The MachInfo module is a static module. Its main purpose is to query for certain machine hardware information or compile options. This information may be used by application software to determine certain computational strategies such as number of processors to use in a parallel computation.

The MachInfo module supports the following functions.

The MachInfo query functions generally use non-standard, system dependent facilities to determine the requested information. Not all possible computer systems are supported. In addition to the queried value, each machine function returns a status flag indicating whether the query is supported on a particular platform. If the query is not supported the queried value is undefined.

Compiled options may also be queried. Each compiled option query returns a single status flag indicating whether the option has been compiled or not. The compile options are those options which require non-standard libraries to be present such as the sockets, threads etc. The compile options queries which are supported are those which require compile flags of the form VKI_LIBAPI_xxxx. Currently query for VKI_LIBAPI_SOCKETS is supported.

8.1.1. Function Descriptions

The currently available MachInfo functions are described in detail in this section.

void vut_MachInfoNumProc(Vint *flag, Vint *numproc)

query number of processors

Query for the number of processors. If the query is supported, flag is returned as 1 otherwise it is returned as 0.

Parameters:

  • flag – [out] Query supported flag

  • numproc – [out] Number of processors

void vut_MachInfoUsedMem(Vint *flag, Vint *usedmem)

query used physical memory

Query for the amount of physical memory used in megabytes. If the query is supported, flag is returned as 1 otherwise it is returned as 0.

Parameters:

  • flag – [out] Query supported flag

  • usedmem – [out] Used physical memory in megabytes

void vut_MachInfoTotalMem(Vint *flag, Vint *totalmem)

query total physical memory

Query for the total amount of physical memory in megabytes. If the query is supported, flag is returned as 1 otherwise it is returned as 0.

Parameters:

  • flag – [out] Query supported flag

  • totalmem – [out] Total physical memory in megabytes

void vut_MachInfoPrec(Vint *flag, Vdouble *machprec)

query machine precision

Query for the machine precision. The machine precision is the smallest number which can be added to 1. and affect the result. If the query is supported, flag is returned as 1 otherwise it is returned as 0.

Parameters:

  • flag – [out] Query supported flag

  • machprec – [out] Machine precision

void vut_MachInfoSystemName(Vint *flag, Vchar sysname[])

query system name

Query for a string describing the host system and processor type. The string will not exceed 256 characters including the terminating NULL. If the query is supported, flag is returned as 1 otherwise it is returned as 0.

Parameters:

  • flag – [out] Query supported flag

  • sysname – [out] Name string of system and processor

void vut_MachInfoHostName(Vint *flag, Vchar hostname[])

query host name

Query for a string describing the host name. The string will not exceed 256 characters including the terminating NULL. If the query is supported, flag is returned as 1 otherwise it is returned as 0.

Parameters:

  • flag – [out] Query supported flag

  • hostname – [out] Host name

void vut_MachInfoUserName(Vint *flag, Vchar username[])

query user name

Query for a string describing the user name. The string will not exceed 256 characters including the terminating NULL. If the query is supported, flag is returned as 1 otherwise it is returned as 0.

Parameters:

  • flag – [out] Query supported flag

  • username – [out] User name

void vut_MachInfoObjectSize(Vint *flag, Vint *objectsize)

query sizeof(size_t), addressability

Query for the size in bytes of the file position object. This is computed as sizeof(size_t). This data type is used to represent return values of the sizeof operator and is an indication of the memory address size of the underlying operating system. This query is always supported.

Parameters:

  • flag – [out] Query supported flag

  • objectsize – [out] Size, in bytes, of sizeof object.

void vut_MachInfoFilePosSize(Vint *flag, Vint *filepossize)

query sizeof(long), disk file position

Query for the size in bytes of the file position object. This is computed as sizeof(long). This data type is used to represent disk file offsets and is an indication of the file size supported by the underlying operating system. This query is always supported.

Parameters:

  • flag – [out] Query supported flag

  • filepossize – [out] Size, in bytes, of file position object.

void vut_MachInfoEndian(Vint *flag, Vint *endian)

query little/big endian

Query for the endian of the system. The endian flag is set to 0 for big endian systems and 1 for little endian systems. The flag is returned as 1.

Parameters:

  • flag – [out] Query supported flag

  • endian – [out] Endian flag

void vut_MachInfoLIBAPI_SOCKETS(Vint *flag)

query VKI_LIBAPI_SOCKETS compilation

Query for VKI_LIBAPI_SOCKETS compiled. If this compile option was set during the compilation of the MachInfo module then this flag is returned as 1 otherwise it is returned as 0.

Parameters:

flag – [out] Query compiled option

void vut_MachInfoDateString(Vint *flag, Vchar datestg[])

query current date as string

Query for a string containing the current date. An example of a date string is 29-Jul-03 The string will not exceed 11 characters including the terminating NULL. The flag is returned as 1.

Parameters:

  • flag – [out] Query supported flag, always returned as 1.

  • datestg – [out] Current date as string

void vut_MachInfoDateInteger(Vint *flag, Vint *day, Vint *mon, Vint *year)

query current date as 3 integers

Query for three integers containing the current date. The flag is returned as 1.

Parameters:

  • flag – [out] Query supported flag, always returned as 1.

  • day – [out] Current day of month

  • mon – [out] Current month of year

  • year – [out] Current year

void vut_MachInfoTimeString(Vint *flag, Vchar timestg[])

query current time as string

Query for a string containing the current time. An example of a time string is 05:45:18 The string will not exceed 9 characters including the terminating NULL. The flag is returned as 1.

Parameters:

  • flag – [out] Query supported flag, always returned as 1.

  • timestg – [out] Current time as string

void vut_MachInfoTimeInteger(Vint *flag, Vint *sec, Vint *min, Vint *hour)

query current time as 3 integers

Query for three integers containing the current time. The flag is returned as 1.

Parameters:

  • flag – [out] Query supported flag, always returned as 1.

  • sec – [out] Current second after the minute

  • min – [out] Current minute after the hour

  • hour – [out] Current hours since midnight

void vut_MachInfoVlongString(Vlong lval, Vchar vlongstg[33])

generate text string of Vlong value

Generate a text representation of a Vlong value lval.

Parameters:

  • lval – Value to generate text string

  • vlongstg – [out] Text string of lval

void vut_MachInfoCpuTimes(Vint *flag, Vfloat *usertime, Vfloat *systemtime)

query current cpu user and system times

Query for two floats containing the elapsed cpu user and system times.

Parameters:

  • flag – [out] Query supported flag

  • usertime – [out] Current cpu user time

  • systemtime – [out] Current cpu system time

8.2. Threading - PTask

The PTask module can be used to create and synchronize processing tasks using a threadpool. The implementation uses the C++ standard threading library. PTask provides a generic, system independent interface to building multi-threaded, parallel applications.

Instance a PTask object using vsy_PTaskBegin(). Specify the type of threadpool and the number of threads in the pool using vsy_PTaskDef(). Types include PTASK_EXEC and PTASK_START. A type of PTASK_EXEC enables the use of vsy_PTaskExec() for atomic execution of a set of tasks. A type of PTASK_START enables the use of vsy_PTaskStart() and vsy_PTaskJoin() for initiating and waiting for termination of individual tasks. The function vsy_PTaskGetThreadId() can be used to get the thread id that a particular task is currently using.

vsy_PTaskLock() can be used in critical areas of a function running on a thread to prevent other threads from executing until vsy_PTaskUnlock() is called. This way multiple threads can safely write to memory locations that are common to all threads. Use vsy_PTaskSetMode() to toggle the execution mode between parallel and serial execution of tasks.

8.2.1. Function Descriptions

The currently available PTask functions are described in detail in this section.

vsy_PTask *vsy_PTaskBegin(void)

create an instance of a PTask object

Create an instance of a PTask object. Memory is allocated for the object private data and the pointer to the data is returned.

Destroy an instance of a PTask object using 

void vsy_PTaskEnd (vsy_PTask *ptask)

Return the current value of a PTask object error flag using 

Vint vsy_PTaskError (vsy_PTask *ptask)

Returns:

The function returns a pointer to the newly created PTask object. If the object creation fails, NULL is returned.

void vsy_PTaskEnd(vsy_PTask *p)

destroy an instance of a PTask object

See vsy_PTaskBegin()

Vint vsy_PTaskError(vsy_PTask *p)

return the current value of a PTask object error flag

See vsy_PTaskBegin()

void vsy_PTaskDef(vsy_PTask *p, Vint numthreads, Vint type)

define a threadpool size and type

Specify the size of the threadpool and the type. The type of PTASK_EXEC enables the use of vsy_PTaskExec(). The type of PTASK_START enables the use of vsy_PTaskStart() and vsy_PTaskJoin(). They are mutually exclusive.

Return the size and type of the threadpool. 

void vsy_PTaskInq (const vsy_PTask *ptask,
                   Vint *numthreads,
                   Vint *type)

Errors

  • SYS_ERROR_ENUM is generated if an improper type is specified.

  • SYS_ERROR_VALUE is generated if numthreads is less than 1

Parameters:

  • p – Pointer to PTask object.

  • numthreads – Size of threadpool

  • type – [out] One of PTASK_EXEC or PTASK_START

void vsy_PTaskInq(const vsy_PTask *p, Vint *num, Vint *type)

return the size and type of the threadpool

See vsy_PTaskDef()

void vsy_PTaskExec(vsy_PTask *p, Vint ntasks, Vfunc1 *func, Vobject **data)

execute a set of tasks

Initiate execution of a set of ntasks tasks starting at the function func. The array of pointers data contains a pointer to data for each of ntasks tasks. The first task is executed by the function func with argument data[0], the second task with argument data[1], etc.

Errors

SYS_ERROR_VALUE is generated if the number of tasks is less than 1.

Parameters:

  • p – Pointer to PTask object.

  • ntasks – Number of tasks

  • func – Pointer to function

  • data – Array of pointers to data

void vsy_PTaskStart(vsy_PTask *p, Vfunc1 *func, Vobject *data, Vint *taskid)

starts a task

Initiate execution of a tasks starting at the function func. data contains a the data for the tasks. The taskid is one based. Once a task is initiated in a thread you can wait for its completion using vsy_PTaskJoin(), using the taskid as a task identifier.

Parameters:

  • p – Pointer to PTask object.

  • func – Pointer to function

  • data – Pointer to function data

  • taskid – [out] A task number that identifies it

void vsy_PTaskLock(vsy_PTask *p)

starts serial execution block

This call provides the functionality of a mutex. Once called, execution will proceed on only one thread until vsy_PTaskUnlock() is called, at which time another thread will be able to proceed. The order in which this serial execution is performed among the threads is randomly assigned.

Parameters:

p – Pointer to PTask object.

void vsy_PTaskUnlock(vsy_PTask *p)

ends serial execution block

This releases the lock created with vsy_PTaskLock(), thus allowing other threads to lock the mutex.

Parameters:

p – Pointer to PTask object.

void vsy_PTaskJoin(vsy_PTask *p, Vint taskid)

waits for termination of a thread

Pauses the execution of the program until the thread identified by taskid completes.

Errors

SYS_ERROR_VALUE is generated if taskid is not valid

Parameters:
void vsy_PTaskGetThreadId(vsy_PTask *p, Vint *num)

get thread id

Returns the id of the current thread. Thread ids are one based.

Parameters:

  • p – Pointer to PTask object.

  • num – [out] The thread id

void vsy_PTaskSetMode(vsy_PTask *p, Vint mode, Vint flag)

set execution mode

The PTASK_SERIALMODE mode is used to force serial task execution when calling either vsy_PTaskExec() or vsy_PTaskStart(). By default PTASK_SERIALMODE mode is off.

Errors

SYS_ERROR_ENUM is generated if an improper mode is specified.

Parameters:

  • p – Pointer to PTask object.

  • mode – Serial mode 

    x=PTASK_SERIALMODE Serial mode

  • flag – Mode flag 

    =SYS_OFF      Turn mode off
=SYS_ON       Turn mode on

8.3. Timers - Timer

The Timer module can be used to accumulate user and system time spent traversing a collection of application code sections or “timed sections”. Each timed section is identified by a name string. The Timer object may expand to contain any number of timed sections. It also supports “iterator” functions which are used to successively visit each timed section stored in the timer.

Instance a Timer object using vsy_TimerBegin(). Once a Timer is instanced, an approximate number of timed sections to be maintained may be defined using vsy_TimerDef(). Each timed section in the Timer object maintains an accumulated user and system time and the total number of timed intervals which have been accumulated. Each timed section is identified by a name string. This name string could be a function name for example. A timing interval is started by calling vsy_TimerStart(). This starts timing for a specified timed section. The timing interval is stopped by calling vsy_TimerStop(). The total number of times that a timed section is started and stopped is the number of timing intervals. The user and system times occurring within this timed interval will be accumulated to the total user and system times for the timed section. The first time a timing interval is started for a timed section all timing information is initialized. The timing information for a timed section may be accessed using vsy_TimerEval(). The timing interval does not need to be stopped to call vsy_TimerEval().

The timing information for a timed section may be explicitly initialized by calling vsy_TimerInit(). Any timed section may be removed by calling vsy_TimerRemove(). All timed sections may be removed by calling vsy_TimerClear().

The pair of methods vsy_TimerInitIter() and vsy_TimerNextIter() are used to visit each timed section using a loop. Call the first method before the body of the loop to prepare the Timer object for the iteration. Within the loop body, call vsy_TimerNextIter(). It will return a pointer to the name string of a timed section each time it is called. It will return a NULL pointer when all of the timed sections have been processed.

The Timer module uses a set of platform dependent timing facilities. If for some reason the user wishes to eliminate the dependency on these timing facilities, and subsequently the function of Timer, a C preprocessor definition, VKI_TIMER_NONE, may be used to conditionally compile the Timer source with the platform dependent functions removed. The effect on Timer will be that the function vsy_TimerEval() will always return zero times.

8.3.1. Function Descriptions

The currently available Timer functions are described in detail in this section.

vsy_Timer *vsy_TimerBegin(void)

create an instance of a Timer object

Create an instance of a Timer object. Memory is allocated for the object private data and the pointer to the data is returned.

Destroy an instance of a Timer object using 

void vsy_TimerEnd (vsy_Timer *timer)

Return the current value of a Timer object error flag using 

Vint vsy_TimerError (vsy_Timer *timer)

Returns:

The function returns a pointer to the newly created Timer object. If the object creation fails, NULL is returned.

void vsy_TimerEnd(vsy_Timer *p)

destroy an instance of a Timer object

See vsy_TimerBegin()

Vint vsy_TimerError(vsy_Timer *p)

return the current value of a Timer object error flag

See vsy_TimerBegin()

void vsy_TimerDef(vsy_Timer *p, Vint numsec)

define an estimated number of timed sections

Suggest a number of timed sections to be stored in the Timer. This function removes any previously stored timed sections.

Find the number of timed sections which may be managed with the presently allocated storage using 

void vsy_TimerInq (const vsy_Timer *timer,
                   Vint *numsec)

Errors

SYS_ERROR_MEMORY is generated if new storage was unable to be allocated.

Parameters:

  • p – Pointer to Timer object.

  • numsec – Estimated number of timed sections to be held.

void vsy_TimerInq(const vsy_Timer *p, Vint *len)

find the number of timed sections which may be managed with the presently allocated storage

See vsy_TimerDef()

void vsy_TimerStart(vsy_Timer *p, const Vchar *name)

start timing a timed section

Start timing interval for timed section, name. If the timed section does not exist it is created.

Errors

SYS_ERROR_OPERATION is generated if a timing interval for the timed section is already running.

Parameters:

  • p – Pointer to Timer object.

  • name – Name string of timed section

void vsy_TimerStop(vsy_Timer *p, const Vchar *name)

stop timing a timed section

Stop timing interval for timed section, name.

Errors

SYS_ERROR_OPERATION is generated if a timing interval for the timed section is not running or the timed section does not exist.

Parameters:

  • p – Pointer to Timer object.

  • name – Name string of timed section

void vsy_TimerInit(vsy_Timer *p, const Vchar *name)

zero times for a timed section

Initialize timing information for timed section, name. If the timed section does not exist it is created.

Parameters:

  • p – Pointer to Timer object.

  • name – Name string of timed section

void vsy_TimerEval(vsy_Timer *p, const Vchar *name, Vint *nintervals, Vint *running, Vfloat *usrtime, Vfloat *systime, Vfloat *elatime)

evaluate current times

Get timing information for timed section, name. If a timing interval has been started and not stopped then the running flag will be SYS_ON. If the timing interval is stopped then running flag will be SYS_OFF. Times are returned in seconds.

Errors

SYS_ERROR_OPERATION is generated if the timed section does not exist.

Parameters:

  • p – Pointer to Timer object.

  • name – Name string of timed section

  • nintervals – [out] Number of timing intervals

  • running – [out] Timing interval in process flag

  • usrtime – [out] Total user time

  • systime – [out] Total system time

  • elatime – [out] Total elapsed time

void vsy_TimerRemove(vsy_Timer *p, const Vchar *name)

remove a specified timed section

Remove timed section name. If the timed section does not exist no action is taken.

Parameters:

  • p – Pointer to Timer object.

  • name – Name string of timed section

void vsy_TimerClear(vsy_Timer *p)

remove all timed sections

Remove all timed sections.

Parameters:

p – Pointer to Timer object.

void vsy_TimerInitIter(vsy_Timer *p)

successively visit each timed section

Sequential access to timed section in the timer may be performed using vsy_TimerInitIter() and vsy_TimerNextIter(). Call vsy_TimerInitIter() to initiate the iteration. Each call of the method vsy_TimerNextIter() will return a pointer to the name of the next timed section. After every timed section has been visited in this manner, vsy_TimerNextIter() will return a NULL pointer until the iteration is restarted using vsy_TimerInitIter().

Parameters:

p – Pointer to Timer object.

void vsy_TimerNextIter(vsy_Timer *p, Vchar **name)

successively visit each timed section

See vsy_TimerInitIter()

Parameters:

  • p – Pointer to Timer object.

  • name – [out] Pointer to name string of timed section

8.4. Socket Communication - VSocket

The VSocket module is designed to allow for communication between sockets, even in heterogeneous systems. Functions are provided to facilitate the exchange of strings of any length, as well as for general multi-byte exchanges. VSocket provides an internal debugging mechanism that can be employed by the user to verify that the exchange is proceeding as expected.

Instance a VSocket object in each of the communicating processes using vsy_VSocketBegin(). Once a VSocket object is instanced, use vsy_VSocketDef() to specify the whether the process is to be considered a server or a client, and the type of connection to be used. A server can communicate with many client processes through a single port, and remains active waiting listening for new clients to accept. If a network connection is used, then the port id and the host name for the connection are set with vsy_VSocketSetNet(). For a local connection, a local file name is set with vsy_VSocketSetLocal().

Next the VSocket object must be opened to allow inter-process communication. It is important that every byte being written by one VSocket object be read by its corresponding VSocket object; otherwise, the socket connection may hang while either is waiting for the other. VSocket has a time-out mechanism to prevent processes from waiting too long.

If VSocket has been defined as the server, use vsy_VSocketAccept() to accept a new connection from a client. Since many clients may communicate with the server simultaneously it is good practice to put this function inside an infinite loop. In addition, in order to put the server in a position where it is ready to accept new clients, client-server communication within the server is usually performed as a separate thread as shown in the example exam22server.c.

Information can be exchanged via two mechanisms: either by writing a fixed number of bytes with vsy_VSocketWrite() whose size the reader knows about and can read with vsy_VSocketRead(), or by writing a null-terminated string with vsy_VSocketWriteString(), which the reader processes with vsy_VSocketReadString(). Note that no byte-swapping is performed between heterogeneous systems as there is no way for VSocket to know the size of each variable to be swapped. Users can detect whether byte swapping is necessary by writing a known number from one process that can be read in the other process and verified.

The function vsy_VSocketSetParami() may be called to modify the default time-out time of 60 seconds, to activate an internal debugging mechanism, or to set the maximum number of active clients supported by the server. The debugging mechanism will print to the console information about every read and write statement processed by the VSocket object. If a string is processed, it is fully displayed.

8.4.1. Function Descriptions

The currently available VSocket functions are described in detail in this section.

vsy_VSocket *vsy_VSocketBegin(void)

create an instance of a VSocket object

Create an instance of an VSocket object. Memory is allocated for the object private data and the pointer to the data is returned.

Destroy an instance of a VSocket object using 

void vsy_VSocketEnd (vsy_VSocket *vsocket)

Return the current value of a VSocket object error flag using 

Vint vsy_VSocketError (vsy_VSocket *vsocket)

Returns:

The function returns a pointer to the newly created VSocket object. If the object creation fails, NULL is returned.

void vsy_VSocketEnd(vsy_VSocket *p)

create an instance of a VSocket object

See vsy_VSocketBegin()

Vint vsy_VSocketError(vsy_VSocket *p)

return the current value of a VSocket object error flag

See vsy_VSocketBegin()

void vsy_VSocketDef(vsy_VSocket *p, Vint type, Vint scope)

define the parameters for the socket connection

Specify the socket parameters. Sockets always come in pairs; one must be defined as the server, and the other as the client. The definition is arbitrary and immaterial for the socket’s use. If both client and server applications reside on the same machine, then it is more efficient to use a scope of VSOCKET_LOCAL. Otherwise, VSOCKET_NET is required as the sockets will communicate through TCP/IP.

If VSOCKET_NET is selected, communication is done via a port number, which must be the same for the server and the client. Both the server and the client require the specification of the server’s host name; for the server, this is done for verification; for the client, to allow for the connection to be established.

If VSOCKET_LOCAL is selected, communication is done via a file common to both the client and the server applications. The file is automatically deleted when the connection is closed. VSOCKET_LOCAL is not supported for Windows.

Find the socket parameters in a previously defined socket using 

void vsy_VSocketInq (const vsy_VSocket *vsocket,
                     Vint *type,
                     Vint *scope)

Errors

  • SYS_ERROR_ENUM is generated if an improper type or scope is specified.

  • SYS_ERROR_ENUM is generated if VSOCKET_LOCAL is selected in Windows.

  • SYS_ERROR_OPERATION is generated if socket is still open.

Parameters:

  • p – Pointer to VSocket object.

  • type – One of VSOCKET_SERVER or VSOCKET_CLIENT

  • scope – One of VSOCKET_LOCAL or VSOCKET_NET

void vsy_VSocketSetNet(vsy_VSocket *p, Vushort portnumber, Vchar serverhost[])

set network connection parameters

Specify the socket components. Sockets always come in pairs; one must be defined as the server, and the other as the client. The definition is arbitrary and immaterial for the socket’s use. Communication is done via a port number, which must be the same for the server and the client. Both the server and the client require the specification of the server’s host name; for the server, this is done for verification; for the client, to allow for the connection to be established.

Errors

  • SYS_ERROR_VALUE is generated if portnumber < 1.

  • SYS_ERROR_OPERATION is generated if socket is still open.

Parameters:

  • p – Pointer to VSocket object.

  • portnumber – Port number to establish the connection

  • serverhost – Name of the server machine to be defined with VSOCKET_SERVER

void vsy_VSocketSetLocal(vsy_VSocket *p, Vchar localfile[])

set local connection parameters

Specify the file on the local machine that will be used by both the client and the server applications. This file is automatically deleted once the connection is closed.

Errors

SYS_ERROR_OPERATION is generated if socket is still open.

Parameters:

  • p – Pointer to VSocket object.

  • localfile – Name of local file for connection

void vsy_VSocketInq(vsy_VSocket *p, Vint *type, Vint *scope)

find the socket parameters in a previously defined socket

See vsy_VSocketDef()

void vsy_VSocketOpen(vsy_VSocket *p)

open a socket connection

Opens a VSocket connection. If VSocket has been defined as a server, this function will bind the object to the server and put it in listening mode. If VSocket has been defined as a client, this function will attempt to connect to the server specified in vsy_VSocketDef().

Errors

SYS_ERROR_OPERATION is generated if vsy_VSocketDef() has not been called; or if VSocket is unable to locate the server machine; or if the socket cannot be created. If client, SYS_ERROR_OPERATION is generated if a connection with the server cannot be established within the time-out period. If server, SYS_ERROR_OPERATION is generated if VSocket is unable to bind the address to the socket, if unable to listen to the socket, or if unable to accept the socket. SYS_ERROR_MEMORY is generated if VSocket is unable to allocate internal auxiliary memory.

Parameters:

p – Pointer to VSocket object.

void vsy_VSocketAccept(vsy_VSocket *p, Vint *cid)

accepts a new client connection

Put the server in a position to accept another client. Note that this function only returns if the maximum number of clients as specified with the integer parameter VSOCKET_MAXCLIENTS has been reached, or if a new client is accepted. If the maximum number of clients has not been reached, this function could potentially take a long time to return, as it must wait for a connection request from a client.

The returned socket id cid can be used by the application to distinguish communication among several clients as all communication functions - e.g. vsy_VSocketWriteString() - require a client id.

Errors

SYS_ERROR_OPERATION is generated if VSocket has been defined as a client, or if the server is unable to accept the client.

Parameters:

  • p – Pointer to VSocket object.

  • cid – The client’s id

void vsy_VSocketClose(vsy_VSocket *p, Vint cid)

close the socket connection

Close a socket connection. If VSocket has been defined as a server, then cid is the client id whose connection is to be closed. In this case, if cid is set to zero, all active client connections are closed. If VSocket has been defined as a client then cid is ignored.

Errors

SYS_ERROR_VALUE is generated if VSocket has been defined as a server and cid is not a valid connection id.

Parameters:

  • p – Pointer to VSocket object.

  • cid – Client id

void vsy_VSocketRead(vsy_VSocket *p, Vint cid, Vint buflen, Vchar *buffer)

read a byte stream sent by its peer

Read a byte stream of data sent by the peer process with vsy_VSocketWrite(). If the data must be swapped, it is the user’s responsibility to perform the swapping.

If VSocket has been defined as a server, then cid is the socket connection the data is to be retrieved from. If VSocket has been defined as a client, then cid is ignored.

Errors

  • SYS_ERROR_OPERATION is generated if VSocket is not opened.

  • SYS_ERROR_FILE is generated if unable to read the required number of bytes.

  • SYS_ERROR_VALUE is generated if VSocket has been defined as a server and cid is not a valid connection id.

Parameters:

  • p – Pointer to VSocket object.

  • cid – Client id

  • buflen – Buffer length in bytes

  • buffer – [out] Buffer to be filled during read

void vsy_VSocketReadString(vsy_VSocket *p, Vint cid, Vint buflen, Vchar *buffer, Vint *size)

read a null-terminated string

Read a null-terminated string sent by the peer process with vsy_VSocketWriteString(). Specify the buffer size in buflen. The actual number of characters read is returned in size. If the null character is encountered after buflen characters are read, the resulting string will be truncated to fit into the declared space, size will reflect the true size of the string sent by the peer process, and no error is generated. If the string fits within the specified space, size will be equal to the result of strlen(buffer).

If VSocket has been defined as a server, then cid is the socket connection the data is to be received from. If VSocket has been defined as a client, then cid is ignored.

Errors

  • SYS_ERROR_OPERATION is generated if VSocket is not opened.

  • SYS_ERROR_FILE is generated if unable to read until a null character is encountered.

  • SYS_ERROR_VALUE is generated if VSocket has been defined as a server and cid is not a valid connection id.

Parameters:

  • p – Pointer to VSocket object.

  • cid – Client id

  • buflen – Size of buffer to receive null-terminated string

  • buffer – [out] Buffer to be filled during read

  • size – [out] Number of characters read

void vsy_VSocketWrite(vsy_VSocket *p, Vint cid, Vint buflen, Vchar *buffer)

write a byte stream to its peer

Write a byte stream of data to the peer process to be read with vsy_VSocketRead().

If VSocket has been defined as a server, then cid is the socket connection the data is to be sent to. If VSocket has been defined as a client, then cid is ignored.

Errors

  • SYS_ERROR_OPERATION is generated if VSocket is not opened.

  • SYS_ERROR_FILE is generated if unable to write the required number of bytes.

  • SYS_ERROR_VALUE is generated if VSocket has been defined as a server and cid is not a valid connection id.

Parameters:

  • p – Pointer to VSocket object.

  • cid – Client id

  • buflen – Buffer length in bytes

  • buffer – Buffer to be sent to peer

void vsy_VSocketWriteString(vsy_VSocket *p, Vint cid, Vchar *buffer)

sends a null-terminated string

Write a null-terminated string to be read by the peer process with vsy_VSocketReadString().

If VSocket has been defined as a server, then cid is the socket connection the data is to be sent to. If VSocket has been defined as a client, then cid is ignored.

Errors

  • SYS_ERROR_OPERATION is generated if VSocket is not opened.

  • SYS_ERROR_FILE is generated if unable to send data to peer

  • SYS_ERROR_VALUE is generated if VSocket has been defined as a server and cid is not a valid connection id.

Parameters:

  • p – Pointer to VSocket object.

  • cid – Client id

  • buffer – Buffer to be sent to peer

void vsy_VSocketSetParami(vsy_VSocket *p, Vint type, Vint iparam)

set parameters

Set socket parameters. The VSOCKET_WAITTIME parameter may be used set the time-out time, in seconds. Defaults to 60 seconds.

The VSOCKET_DEBUG parameter may be used to toggle to enable/disable debugging. Defaults SYS_OFF. If set to SYS_ON, debugging messages are sent to the console. Every debugging message is preceded by the string hostname_client_portid or hostname_server_portid. Every vsy_VSocketRead() statement echoes the number of bytes received upon completion; every vsy_VSocketWrite() statement echoes the number of bytes sent upon completion; every vsy_VSocketReadString() statement displays the string received, along with a string counter; every vsy_VSocketWriteString() statement displays the string sent, along with a string counter. One separate counter is maintained for sent and received strings. Counters are incremented on every call, regardless whether VSOCKET_DEBUG is set to SYS_ON. Counters are reset during a call to vsy_VSocketOpen().

The VSOCKET_MAXCONNECTION parameter may be set to specify the maximum number of active client connections on the server. Defaults to 5.

Errors

SYS_ERROR_ENUM is generated if an improper type is specified.

Parameters:

  • p – Pointer to VSocket object.

  • type – Type of parameter to set 

    x=VSOCKET_WAITTIME       Time-out time in seconds
 =VSOCKET_DEBUG          Toggle enable/disable debugging
 =VSOCKET_MAXCONNECTION  Maximum number of client connections

  • iparam – Specifies the integer value that type will be set to.