Get the CSN address of a transport
#include <csn/csn.inc>
integer function csngetid(itransport) integer itransport
This function gets the CSN address of the local transport i transport.
csngetnet(),csngetnode(),csngettransport(),csnmakeid().
15
csngetnetO Synopsis Description
See Also
16
Extract network number from CSN address
#include <csn/csnrncs.inc>
csngetnet(peerid)
This statement function is defined in the header file, <csn/ csnrncs. inc>. It returns the network number from the CSN address, peer id, that is passed as an argument.
CSN addresses (as returned by csnlookupnarne () and other CSN functions), consist of three parts: the network number, the node number, and the transport number.
csngetnode(),csngettransport(),csnrnakeid().
SlOO2-10MI07.05
meJ<a
csngetnode() Synopsis Description
See Also
rneko
Reference ManualExtract node number from CSN address
#include <csn/csnmcs.inc>
csngetnode(peerid)
This statement function is defined in the header file, <csn/ csnmcs . inc>. It returns the node number from the CSN address, peerid, that is passed as an ar-gument.
CSN addresses (as returned by csnlookupname () and other CSN functions), consist of three parts: the network number, the node number, and the transport number.
csngetnet(),csngettransport(),csnmakeid()
17
csngettransportO Synopsis
Description
See Also
18
Get transport number from CSN address
#include <csn/csnmcs.inc>
csngettransport(peerid)
This statement function is defined in the header file, <csn/ csnmcs. inc>. It returns the transport number from the CSN address, peerid, that is passed as an argument. This only makes sense if the relevant transport is local to the proc-essor calling the function.
CSN addresses (as returned by csnlookupname () and other CSN functions), consist of three parts: the network number, the node number, and the transport number.
csngetnet(),csngetnode(),csnmakeid().
SlOO2-10MI07.05
mei<a
csninitO Synopsis Description
meko
Reference ManualInitialise the CSN
#include <csn/csn.inc>
subroutine csninit()
This subroutine sets up the network connection between the current process and the CSN network - it must be the first function that is called by the process.
Before the CSN can be used, the subroutine csninit () must be called to per-form any system initialisation which may be required. After calling csnin-it () , a program will normally create a set of Transports (using csnopen (»), give each of the transports a meaningful name (using csnregname (»), and then (using csnlookupname ()) discover the addresses of the transports to which it intends to transmit. It is normal for all programs to create their transports before looking up any others to avoid potential deadlocks where two programs are each waiting for the other to create and register a transport.
19
csnlookupname() Synopsis
Description
Example
See Also
20
Look-up a named Transport
#include <csn/names.inc>
integer function csnlookupname(inetaddr,cname,lblock) integer inetaddr
character *(*) cname logical lblock
This function looks up the name, cname, and returns the associated CSN address in the variable, inetaddr. The argument, lblock, determines the behaviour of the function when the given name has not yet been registered. If lblock is
. true. then csnlookupname ( ) does not return until the name is registered, otherwise csnlookupname () returns immediately with an error status as its result. Note that it is advisable that a process always registers transport names be-fore looking-up, to prevent deadlock. If this advice is not followed, you should not set lblock to . true ..
Here is a sample code fragment which looks up a transport called MASTER.
C
C Find the master
C
if (csnlookupname(masterTpt,'MASTER', .TRUE.) .ne. CSN OK) then stop 'Slave can't find master'
end if
csnregname(),csnderegname().
SlOO2-10MI07.05
me/<o
csnmakeidO Synopsis Description
See Also
meko
Reference ManualAssemble CSN address
#include <csn/csnmcs.inc>
csnmakeid(netid, nodeid, transportid)
This statement function is defined in the header file, <csn/ csnmcs. inc>. It assembles a CSN address from a network number, netid, a node number, no-deid, and a transport number, transportid.
CSN addresses (as returned by csnlookupname () and other CSN functions), consist of three pans: the network number, the node number, and the transport number.
Warning - In the current implementation netid must be O.
Warning - Manipulation of the internal structure of network addresses is not recommended.
csngetnet(),csngetnode(),csngettransport().
21
csnnodesO Synopsis Description See Also
22
N umber of Processors
#include <csn/csn.inc>
integer function csnnodes();
Parallel programs are run one process per processor on the CS-2. This function returns the number of processors executing this application.
csnnode ().
SIOO2-10MI07.05
meJ<a
csnnodeO Synopsis Description
See Also
mei<o
Reference ManualProcessor Id
include <csn/csn.inc>
integer function csnnode();
Parallel programs are run one process per processor on the CS-2. This function returns the 10 of the processor executing this process. IDs will lie in the range 0 to nodes-I, where nodes is returned by csnnnodes ().
csnnnodes () .
23
csnopenO Synopsis
Description
Example
See Also
24
Open a CSN Transport
#inelude <esn/esn.inc>
integer function csnopen{index, itransport) integer index, itransport
This function allows a program to create a transport, and thus to access the CSN.
The first argument is the network address to give to the created port, or CSN-NULLID to allow the system to choose a suitable address. (Advice: always let the system choose). The second argument is assigned the transport that is created.
The result is zero on success, or a negative value on failure.
To create a transport:
integer mastertpt C
C Create the master transport C
if (csnOpen(CSN NULL ID, mastertpt) .ne. CSN OK) then stop 'Master failed to open a transport'
end if
esnelose(),esnregnarne{),esnlookupname{).
S lOO2-10Ml07 .05
meJ<a
csnregnameO Synopsis
Description
Example
See Also
meI<o
Reference ManualName a CSN Transport
*include <csn/names.inc>
integer function csnregname(itransport, cname) integer itransport
character *(*) cname
This function associates the textual name, cname, with the transport, i trans-port. When the name has been associated, then other processes within the con-figuration can obtain the network address of the transport by perfonning a csnlookupname ( ) .
if (csnRegName(mastertpt,'MASTER') .ne. CSN OK) then stop 'Master failed to regi'ster name " MASTER' , , end if
csnlookupname(),csnderegname().
25
csnrxO Synopsis
Description
Example
See Also
26
Blocking receive via CSN
#include <csn/csn.inc>
integer function csnrx(itransport, ipeerid, ibuffer, imaxsize)
integer itransport, ipeerid, ibuffer, irnaxsize
This function receives a message on transport i transport into the buffer ibuffer. The maximum message size which will be accepted is irnaxsize.
The argument ipeerid must be a VARIABLE, since it is assigned the transport address of the transport from which the received message was sent.
The function returns the number of bytes actually received, or an error code.
To receive a four byte message:
null = CSN NULL 10
i f (csnrx (slavetpt, null, processno, 4) .ne. 4) then stop 'Slave failed to receive process number' end if
processno = processno + 1
call csntx(slavetpt, 0, nexttpt, processno, 4)
csntx (), csnrxnb () .
SlOO2-10MI07.05
meJ<a
csnrxnbO Synopsis
Description
Example
See Also
meI<o
Reference ManualNon-blocking receive via the CSN iinclude <csn/csn.inc>
integer function csnrxnb(itransport, ibuffer, imaxsize, itag}
integer itransport, ibuffer(*), imaxsize, itag
This routine is the non-blocking analogue of csnrx () . It is used to queue a buffer into which reception of messages will occur. As with c s n t xnb () the tag is used to identify this particular transaction to csntest ( ) .
Here is a call from the master in a load balancer in which it queues up a number of buffers to receive results from the slaves. An array of buffers is used, the index of the buffer being used as its tag.
c
C First queue up the result buffers, their tags are negated, so C that they can easily be distinguished from the job buffers when C we do the csnTest.
C
do i = 1, nresultbuffe.rs
call csnrxnb(mastertpt, resultBuffer(O,i), + (resultSize+l) *4, -i)
end do
csntxnb ( ) , csnrx () .
27
csnstatusstring() Synopsis
Description
28
Return CSN error string
#include <csn/csn.inc>
character *(*) csnstatusstring(ierrno) integer ierrno
This function returns a string containing a textual version of the CSN error code ierrno.
SlOO2-10MI07.05
meJ<a
csntestO Synopsis
Description
mei<o
Reference ManualTest for completion of non-blocking communication
*include <csn/csn.inc>
integer function csntest (itransport, iflags,
timeout, ipeerid, itag, status) integer itransport, iflags, timeout
integer ipeerid, itag, status
This routine tests for the completion of communications initiated by the non-blocking calls c s nt xnb () and c s nrxnb ( ) . It waits for timeout microseconds (or forever if the timeout argument is CSNNULLTIMEOUT) for a buffer meet-ing the criteria set by the if lags and i tag arguments to be found.
The if lags argument determines what sort of communication is being tested for completion, it can be 0 meaning either transmission or reception, or one of the values CSNTXREADY or CSNRXREADY to test for the readiness of a buff-er queued by csntxnb () or csnrxnb () respectively.
The ipeer id argument must be a variable, since it is assigned within the func-tion with the value of the network address with which the successful communi-cation took place. In addition if the value on entry to the function is not CSNNULLID, then only buffers involved in communication with that specific network address are considered. (Note that it is an easy bug to forget to re-assign CSNNULLID to the variable passed to the formal argument ipeerid, this has the effect of unnecessaril y filtering the c s n t est () call, and will manifest itself either as a deadlock, or a starvation of all but one other network address).
The i tag argument must be a variable, since it is assigned the tag which was associated with the buffer whose communication has completed. As with the ipeerid the initial value of the i tag argument is used as a selection criterion, so if all buffers are to be considered then the itag formal argument must be as-signed the value CSNNULLTAG.
Warning - csntest () must be used to free-up the memory used by non-blocking communications.
The return values from csntest () are as follows:
29
See Also
30
CSNTXREADY CSNRXREADY
o
CSNEBADREQ CSNEABORT
A communication initiated by csntxnb () completed or cancelled.
A communication initiated by csnrxnb () completed or cancelled.
No specified communications completed and at least timeout microseconds had elapsed.
Illegal values for flags.
Transport was closed while csntest () was blocked.
Note that a transport may only be closed after all
outstanding communications on it have completed. When either CSNTXREADY or CSNRXREADY are returned, the value of status may be used to detennine if the communication completed or was cancelled. stat us is set to CSNEABORT if it was cancelled.
csntxnb (), csnrxnb () .
SlOO2-10MI07.05
meJ<o
csntxO Synopsis
Description
Example
See Also
mei<D
Reference ManualBlocking transmission via CSN
#include <csn/csn.inc>
integer function csntx(itransport, iflags, ipend, ibuffer, isize)
integer itransport, iflags, ipend, ibuffer, isize This function transmits a message through the transport itransport to the transport whose address is ipend. The message data is taken from ibuffer, and the number of bytes transmitted is isize. The argument if lags is not cur-rently used and should be set to O.
The function will not return until either an error can be detected, or the data has been placed in a user buffer at the recipient. The result returned is the number of bytes sent if the transmission was successful, or an error return if the transmis-sion failed.
To send the 4 byte integer, 0, through the transport mastertpt:
c
C Inject zero into the fr.ont of the pipe C
if (csntx(mastertpt, 0, nexttpt, 0, 4) .ne. 4) then stop 'Master can"t inject zero into pipe'
end if
csnrx (), csntxnb () .
31
csntxnbO
Non-blocking transmission via CSN
#inelude <esn/esn.ine>
integer function esntxnb(itransport, iflags, peerid, ibuffer, isize, itag)
integer itransport, iflags, peerid integer ibuffer(*), isize, itag
The arguments to this routine are identical to those for csntx () , but with an ad-ditional i tag argument. This is used to identify this transaction when querying its status using esntest () . The return from the function occurs as soon as the buffer has been queued, thus a successful return from esntxnb () does not im-ply that the data has been sent yet, merely that there were sufficient local resourc-es to requresourc-est transmission. The return status for the whole transaction is returned by the call to e s n t est () which returns this buffer. The contents of the buffer will not be copied by the system, and should not therefore be modified until the system has returned ownership of the buffer by returning it as the result of a es-ntest () call.
Here is a call from the master in a load balancer which is queuing a job to send to a slave. Here the master has allocated a two dimensional array to serve as buff-ers, each column representing a single buffer. The column index is then used as the tag, so that the correct buffer can be reused when the esntest () is com-plete.
c
C There is a job to be done, so queue it.
C
call csntxnb(mastertpt, 0, slavetpt(i), + jobbuffer(O,i), (jobsize+l) *4, i)
csntx (), esnrxnb () .
SlOO2-10MI07.05
meJ<.o
Overview
mei<a
This chapter includes a number of examples showing how to use the CSN com-munication library. It discusses the use of transports and the choice of blocking versus non-blocking communications.
Compilation and Execution
All the examples in this chapter can be compiled with the following command line:
user@cs2: £77 -0 myprogram -I/opt/MEIKOes2/ine~ude \
-L/opt/MEIKOes2/~ib myprogram -lesn -lew -le~an
The programs are executed with prun(l) and will use command lines like that shown below. Note that number is the number of processors required, partition is the name of the partition that you will use, and myprogram is the name of the program.
user@cs2: prun -nnumber -ppartition myprogram
Full infonnation about prun(l) command may be obtained from the reference manual page.
33