Table of Contents

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.

Table of Contents

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.

Table of Contents

8.2 Function Descriptions

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


Table of Contents , MachInfo

NAME

vut_MachInfoNumProc - query number of processors

C SPECIFICATION

void vut_MachInfoNumProc (Vint *flag,
                          Vint *numproc)

INPUT ARGUMENTS

None

OUTPUT ARGUMENTS

flag         Query supported flag
numproc      Number of processors

DESCRIPTION

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


Table of Contents , MachInfo

NAME

vut_MachInfoFilePosSize - query sizeof(long), disk file position

C SPECIFICATION

void vut_MachInfoFilePosSize (Vint *flag,
                              Vint *filepossize)

INPUT ARGUMENTS

None

OUTPUT ARGUMENTS

flag         Query supported flag
filepossize  Size, in bytes, of file position object.

DESCRIPTION

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.


Table of Contents , MachInfo

NAME

vut_MachInfoObjectSize - query sizeof(size_t), addressability

C SPECIFICATION

void vut_MachInfoObjectSize (Vint *flag,
                             Vint *objectsize)

INPUT ARGUMENTS

None

OUTPUT ARGUMENTS

flag         Query supported flag
objectsize   Size, in bytes, of sizeof object.

DESCRIPTION

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.


Table of Contents , MachInfo

NAME

vut_MachInfoPrec - query machine precision

C SPECIFICATION

void vut_MachInfoPrec (Vint *flag,
                       Vdouble *machprec)

INPUT ARGUMENTS

None

OUTPUT ARGUMENTS

flag         Query supported flag
machprec     Machine precision

DESCRIPTION

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.


Table of Contents , MachInfo

NAME

vut_MachInfoHostName - query host name

C SPECIFICATION

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

INPUT ARGUMENTS

None

OUTPUT ARGUMENTS

flag         Query supported flag
hostname     Host name

DESCRIPTION

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.


Table of Contents , MachInfo

NAME

vut_MachInfoUserName - query user name

C SPECIFICATION

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

INPUT ARGUMENTS

None

OUTPUT ARGUMENTS

flag         Query supported flag
username     User name

DESCRIPTION

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.


Table of Contents , MachInfo

NAME

vut_MachInfoSystemName - query system name

C SPECIFICATION

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

INPUT ARGUMENTS

None

OUTPUT ARGUMENTS

flag         Query supported flag
sysname      Name string of system and processor

DESCRIPTION

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.


Table of Contents , MachInfo

NAME

vut_MachInfoTotalMem - query total physical memory

C SPECIFICATION

void vut_MachInfoTotalMem (Vint *flag,
                           Vint *totalmem)

INPUT ARGUMENTS

None

OUTPUT ARGUMENTS

flag         Query supported flag
totalmem     Total physical memory in megabytes

DESCRIPTION

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.


Table of Contents , MachInfo

NAME

vut_MachInfoUsedMem - query used physical memory

C SPECIFICATION

void vut_MachInfoUsedMem (Vint *flag,
                          Vint *usedmem)

INPUT ARGUMENTS

None

OUTPUT ARGUMENTS

flag         Query supported flag
usedmem      Used physical memory in megabytes

DESCRIPTION

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.


Table of Contents , MachInfo

NAME

vut_MachInfoEndian - query little/big endian

C SPECIFICATION

void vut_MachInfoEndian (Vint *flag,
                         Vint *endian)

INPUT ARGUMENTS

None

OUTPUT ARGUMENTS

flag         Query supported flag
endian       Endian flag

DESCRIPTION

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.


Table of Contents , MachInfo

NAME

vut_MachInfoDateString - query current date as string

C SPECIFICATION

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

INPUT ARGUMENTS

None

OUTPUT ARGUMENTS

flag         Query supported flag, always returned as 1.
datestg      Current date as string

DESCRIPTION

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.


Table of Contents , MachInfo

NAME

vut_MachInfoTimeString - query current time as string

C SPECIFICATION

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

INPUT ARGUMENTS

None

OUTPUT ARGUMENTS

flag         Query supported flag, always returned as 1.
timestg      Current time as string

DESCRIPTION

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.


Table of Contents , MachInfo

NAME

vut_MachInfoVlongString - generate text string of Vlong value

C SPECIFICATION

void vut_MachInfoVlongString (Vlong lval,
                              Vchar vlongstg[])

INPUT ARGUMENTS

lval         Value to generate text string

OUTPUT ARGUMENTS

vlongstg     Text string of lval

DESCRIPTION

Generate a text representation of a Vlong value lval.


Table of Contents , MachInfo

NAME

vut_MachInfoDateInteger - query current date as 3 integers

C SPECIFICATION

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

INPUT ARGUMENTS

None

OUTPUT ARGUMENTS

flag         Query supported flag, always returned as 1.
day          Current day of month
mon          Current month of year
year         Current year

DESCRIPTION

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


Table of Contents , MachInfo

NAME

vut_MachInfoTimeInteger - query current time as 3 integers

C SPECIFICATION

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

INPUT ARGUMENTS

None

OUTPUT ARGUMENTS

flag         Query supported flag, always returned as 1.
sec          Current second after the minute
min          Current minute after the hour
hour         Current hours since midnight

DESCRIPTION

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


Table of Contents , MachInfo

NAME

vut_MachInfoCpuTimes - query current cpu user and system times

C SPECIFICATION

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

INPUT ARGUMENTS

None

OUTPUT ARGUMENTS

flag         Query supported flag
usertime     Current cpu user time
systemtime   Current cpu system time

DESCRIPTION

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


Table of Contents , MachInfo

NAME

vut_MachInfoLIBAPI_SOCKETS - query VKI_LIBAPI_SOCKETS compilation

C SPECIFICATION

void vut_MachInfoLIBAPI_SOCKETS (Vint *flag)

INPUT ARGUMENTS

None

OUTPUT ARGUMENTS

flag         Query compiled option

DESCRIPTION

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.


Table of Contents

8.3 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.

Table of Contents

8.4 Function Descriptions

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


Table of Contents , PTask

NAME

*vsy_PTaskBegin - create an instance of a PTask object

C SPECIFICATION

vsy_PTask *vsy_PTaskBegin ()

ARGUMENTS

None

FUNCTION RETURN VALUE

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

DESCRIPTION

Create an instance of an 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)


Table of Contents , PTask

NAME

vsy_PTaskDef - define a threadpool size and type

C SPECIFICATION

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

INPUT ARGUMENTS

ptask        Pointer to PTask object.
numthreads   Size of threadpool
type         One of PTASK_EXEC or PTASK_START

OUTPUT ARGUMENTS

None

ERRORS

SYS_ERROR_ENUM is generated if an improper type is specified. SYS_ERROR_VALUE is generated if numthreads is less than 1

DESCRIPTION

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)


Table of Contents , PTask

NAME

vsy_PTaskExec - execute a set of tasks

C SPECIFICATION

void vsy_PTaskExec (vsy_PTask *ptask,
                    Vint ntasks,
                    void (*func)(Vobject*),
                    Vobject *data[])

INPUT ARGUMENTS

ptask        Pointer to PTask object.
ntasks       Number of tasks
func         Pointer to function
data         Array of pointers to data

OUTPUT ARGUMENTS

None

ERRORS

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

DESCRIPTION

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.


Table of Contents , PTask

NAME

vsy_PTaskGetThreadId - get thread id

C SPECIFICATION

void vsy_PTaskGetThreadId (vsy_PTask *ptask,
                           Vint *id)

INPUT ARGUMENTS

ptask        Pointer to PTask object.

OUTPUT ARGUMENTS

num          The thread id

ERRORS

None

DESCRIPTION

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


Table of Contents , PTask

NAME

vsy_PTaskJoin - waits for termination of a thread

C SPECIFICATION

void vsy_PTaskJoin (vsy_PTask *ptask,
                    Vint taskid)

INPUT ARGUMENTS

ptask        Pointer to PTask object.
taskid       Task id generated by vsy_PTaskStart

OUTPUT ARGUMENTS

SYS_ERROR_VALUE is generated if taskid is not valid

ERRORS

None

DESCRIPTION

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


Table of Contents , PTask

NAME

vsy_PTaskLock - starts serial execution block

C SPECIFICATION

void vsy_PTaskLock (vsy_PTask *ptask)

INPUT ARGUMENTS

ptask        Pointer to PTask object.

OUTPUT ARGUMENTS

None

ERRORS

None

DESCRIPTION

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.


Table of Contents , PTask

NAME

vsy_PTaskUnlock - ends serial execution block

C SPECIFICATION

void vsy_PTaskUnlock (vsy_PTask *ptask)

INPUT ARGUMENTS

ptask        Pointer to PTask object.

OUTPUT ARGUMENTS

None

ERRORS

None

DESCRIPTION

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


Table of Contents , PTask

NAME

vsy_PTaskStart - starts a task

C SPECIFICATION

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

INPUT ARGUMENTS

ptask        Pointer to PTask object.
func         Pointer to function
data         Pointer to function data

OUTPUT ARGUMENTS

taskid       A task number that identifies it

ERRORS

None

DESCRIPTION

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.


Table of Contents , PTask

NAME

vsy_PTaskSetMode - set execution mode

C SPECIFICATION

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

INPUT ARGUMENTS

ptask        Pointer to PTask object.
mode         Serial mode
             =PTASK_SERIALMODE Serial mode
flag         Mode flag
             =SYS_OFF      Turn mode off
             =SYS_ON       Turn mode on

OUTPUT ARGUMENTS

None

ERRORS

SYS_ERROR_ENUM is generated if an improper mode is specified.

DESCRIPTION

Toggle execution modes.

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.


Table of Contents

8.5 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.

Table of Contents

8.6 Function Descriptions

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


Table of Contents , Timer

NAME

*vsy_TimerBegin - create an instance of a Timer object

C SPECIFICATION

vsy_Timer *vsy_TimerBegin ()

ARGUMENTS

None

FUNCTION RETURN VALUE

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

DESCRIPTION

Create an instance of an 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)


Table of Contents , Timer

NAME

vsy_TimerDef - define an estimated number of timed sections

C SPECIFICATION

void vsy_TimerDef (vsy_Timer *timer,
                   Vint numsec)

INPUT ARGUMENTS

timer        Pointer to Timer object.
numsec       Estimated number of timed sections to be held.

OUTPUT ARGUMENTS

None

ERRORS

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

DESCRIPTION

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)


Table of Contents , Timer

NAME

vsy_TimerClear - remove all timed sections

C SPECIFICATION

void vsy_TimerClear (vsy_Timer *timer)

INPUT ARGUMENTS

timer        Pointer to Timer object.

OUTPUT ARGUMENTS

None

DESCRIPTION

Remove all timed sections.


Table of Contents , Timer

NAME

vsy_TimerEval - evaluate current times

C SPECIFICATION

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

INPUT ARGUMENTS

timer        Pointer to Timer object.
name         Name string of timed section

OUTPUT ARGUMENTS

nintervals   Number of timing intervals
running      Timing interval in process flag
usrtime      Total user time
systime      Total system time
elatime      Total elapsed time

ERRORS

SYS_ERROR_OPERATION is generated if the timed section does not exist.

DESCRIPTION

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.


Table of Contents , Timer

NAME

vsy_TimerInit - zero times for a timed section

C SPECIFICATION

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

INPUT ARGUMENTS

timer        Pointer to Timer object.
name         Name string of timed section

OUTPUT ARGUMENTS

None

DESCRIPTION

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


Table of Contents , Timer

NAME

vsy_TimerRemove - remove a specified timed section

C SPECIFICATION

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

INPUT ARGUMENTS

timer        Pointer to Timer object.
name         Name string of timed section

OUTPUT ARGUMENTS

None

DESCRIPTION

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


Table of Contents , Timer

NAME

vsy_TimerStart - start timing a timed section

C SPECIFICATION

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

INPUT ARGUMENTS

timer        Pointer to Timer object.
name         Name string of timed section

OUTPUT ARGUMENTS

None

ERRORS

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

DESCRIPTION

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


Table of Contents , Timer

NAME

vsy_TimerStop - stop timing a timed section

C SPECIFICATION

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

INPUT ARGUMENTS

timer        Pointer to Timer object.
name         Name string of timed section

OUTPUT ARGUMENTS

None

ERRORS

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

DESCRIPTION

Stop timing interval for timed section, name.


Table of Contents , Timer

NAME

vsy_TimerNextIter,vsy_TimerInitIter - successively visit each timed section

C SPECIFICATION

void vsy_TimerInitIter (vsy_Timer *timer)

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

INPUT ARGUMENTS

timer        Pointer to Timer object.

OUTPUT ARGUMENTS

name         Pointer to name string of timed section

DESCRIPTION

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.


Table of Contents

8.7 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.

Table of Contents

8.8 Function Descriptions

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


Table of Contents , VSocket

NAME

*vsy_VSocketBegin - create an instance of a VSocket object

C SPECIFICATION

vsy_VSocket *vsy_VSocketBegin ()

ARGUMENTS

None

FUNCTION RETURN VALUE

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

DESCRIPTION

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)


Table of Contents , VSocket

NAME

vsy_VSocketClose - close the socket connection

C SPECIFICATION

void vsy_VSocketClose (vsy_VSocket *vsocket,
                       Vint cid)

INPUT ARGUMENTS

vsocket      Pointer to VSocket object.
cid          Client id

OUTPUT ARGUMENTS

None

ERRORS

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

DESCRIPTION

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.


Table of Contents , VSocket

NAME

vsy_VSocketAccept - accepts a new client connection

C SPECIFICATION

void vsy_VSocketAccept (vsy_VSocket *vsocket,
                        Vint *cid)

INPUT ARGUMENTS

vsocket      Pointer to VSocket object.
cid          The client's id

OUTPUT ARGUMENTS

None

ERRORS

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

DESCRIPTION

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.


Table of Contents , VSocket

NAME

vsy_VSocketDef - define the parameters for the socket connection

C SPECIFICATION

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

INPUT ARGUMENTS

vsocket      Pointer to VSocket object.
type         One of VSOCKET_SERVER or VSOCKET_CLIENT
scope        One of VSOCKET_LOCAL or VSOCKET_NET

OUTPUT ARGUMENTS

None

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.

DESCRIPTION

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)


Table of Contents , VSocket

NAME

vsy_VSocketOpen - open a socket connection

C SPECIFICATION

void vsy_VSocketOpen (vsy_VSocket *vsocket)

INPUT ARGUMENTS

vsocket      Pointer to VSocket object.

OUTPUT ARGUMENTS

None

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.

DESCRIPTION

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.


Table of Contents , VSocket

NAME

vsy_VSocketRead - read a byte stream sent by its peer

C SPECIFICATION

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

INPUT ARGUMENTS

vsocket      Pointer to VSocket object.
cid          Client id
buflen       Buffer length in bytes

OUTPUT ARGUMENTS

buffer       Buffer to be filled during read

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.

DESCRIPTION

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.


Table of Contents , VSocket

NAME

vsy_VSocketReadString - read a null-terminated string

C SPECIFICATION

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

INPUT ARGUMENTS

vsocket      Pointer to VSocket object.
cid          Client id
buflen       Size of buffer to receive null-terminated string

OUTPUT ARGUMENTS

buffer       Buffer to be filled during read
size         Number of characters read

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.

DESCRIPTION

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.


Table of Contents , VSocket

NAME

vsy_VSocketSetLocal - set local connection parameters

C SPECIFICATION

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

INPUT ARGUMENTS

vsocket      Pointer to VSocket object.
localfile    Name of local file for connection

OUTPUT ARGUMENTS

None

ERRORS

SYS_ERROR_OPERATION is generated if socket is still open.

DESCRIPTION

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.


Table of Contents , VSocket

NAME

vsy_VSocketSetNet - set network connection parameters

C SPECIFICATION

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

INPUT ARGUMENTS

vsocket      Pointer to VSocket object.
portnumber   Port number to establish the connection
serverhost   Name of the server machine to be defined with VSOCKET_SERVER

OUTPUT ARGUMENTS

None

ERRORS

SYS_ERROR_VALUE is generated if portnumber < 1. SYS_ERROR_OPERATION is generated if socket is still open.

DESCRIPTION

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.


Table of Contents , VSocket

NAME

vsy_VSocketSetParami - set parameters

C SPECIFICATION

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

INPUT ARGUMENTS

vsocket      Pointer to VSocket object.
type         Type of parameter to set
             =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.

OUTPUT ARGUMENTS

None

ERRORS

SYS_ERROR_ENUM is generated if an improper type is specified.

DESCRIPTION

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.


Table of Contents , VSocket

NAME

vsy_VSocketWrite - write a byte stream to its peer

C SPECIFICATION

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

INPUT ARGUMENTS

vsocket      Pointer to VSocket object.
cid          Client id
buflen       Buffer length in bytes
buffer       Buffer to be sent to peer

OUTPUT ARGUMENTS

None

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.

DESCRIPTION

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.


Table of Contents , VSocket

NAME

vsy_VSocketWriteString - sends a null-terminated string

C SPECIFICATION

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

INPUT ARGUMENTS

vsocket      Pointer to VSocket object.
cid          Client id
buffer       Buffer to be sent to peer

OUTPUT ARGUMENTS

None

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.

DESCRIPTION

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.