1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
|
.TH PSEND 2 "July, 2007" "LAM 7.1.4" "LAM NETWORK LIBRARY"
.hy 0
.SH NAME
psend, precv, psendopen, precvopen, psendclose, precvclose
\- LAM physical layer message passing (virtual circuits)
.SH C SYNOPSIS
.hy 1
.nf
#include <net.h>
int psend (struct nmsg *header);
int precv (struct nmsg *header);
int psendopen (struct nmsg *header);
int precvopen (struct nmsg *header);
int psendclose (struct nmsg *header);
int precvclose (struct nmsg *header);
.fi
.SH FORTRAN SYNOPSIS
.hy 0
.HP
subroutine PSND (pnode, pevent, ptype, plength, pflags, pdata, pdsize,
pmsg, ierror)
.RE
subroutine PSNDO (pnode, pevent, ptype, ierror)
.br
subroutine PSNDC (pnode, pevent, ptype, ierror)
.PP
.HP
subroutine PRCV (pevent, ptype, plength, pflags, pdata, pdsize,
pmsg, ierror)
.RE
subroutine PRCVO (pevent, ptype, ierror)
.br
subroutine PRCVC (pevent, ptype, ierror)
.PP
.HP
integer pnode, pevent, ptype, plength, pflags, pdata(*), pdsize, ierror
.br
.RE
<type> pmsg(*)
.hy 1
.SH DESCRIPTION
These functions use physical connections to establish LAM virtual circuits.
A user can establish a virtual circuit, pass messages on it, and dismantle
it when no longer needed.
Virtual circuits provide the fastest LAM point-to-point communication
speeds, bypassing the LAM daemon, transferring the
messages using the underlying physical connections.
All of these functions accept a pointer to a network message descriptor
(see nsend(2)).
.PP
The
.I psendopen()
and the
.I precvopen()
functions are used, by the sender and receiver respectively, to establish
a point-to-point virtual circuit between them.
To establish a virtual circuit, the sender sets the
.I nh_node
field of the message descriptor to the receiver's nodeid, and the
.I nh_event
and
.I nh_type
fields to specify the synchronization just as in regular message passing
(see nsend(2)).
These fields are not changed after a call to
.IR psendopen() .
On the receiver side, the
.I nh_event
and
.I nh_type
fields have to be set in order for synchronization to take place.
After a call to
.IR precvopen() ,
the
.I nh_event
field is unchanged but the
.I nh_type
field is set to the sender's
.I nh_type
field in order to fully specify the correct virtual circuit created.
Calling
.I psendopen()
and
.I precvopen()
causes the sender and the receiver to block until synchronization
takes place and a virtual circuit is created.
.PP
After successful calls to
.I psendopen()
and
.I precvopen()
a virtual circuit is established and will be used to quickly transfer messages
whenever the sender calls
.I psend()
and the receiver calls
.I precv()
on the nodeid, event, and type specified during its creation.
.I psend()
and
.I precv()
are otherwise used to transfer messages just as
.I nsend()
and
.I nrecv()
would be, and any mismatch in the message length is handled in a
similar manner (see nsend(2)).
Likewise, the data conversion flags can be set by the sender in order
for LAM to change the contents of
.I nh_data
and
.I nh_msg
to the proper local byte order at the receiver.
Calling
.I psend()
and
.I precv()
causes the sender and receiver to block until the message exchange
is completed.
.PP
Since virtual circuits use resources, it is preferable to close them
when they are no longer needed.
The sender closes a virtual circuit by calling the
.I psendclose()
function, specifying the node, event, and type of that virtual circuit.
The receiver closes a virtual circuit by calling the
.I precvclose()
functions, specifying the event and the type as returned by the
.I precvopen()
function.
The
.I psendclose()
and
.I precvclose()
functions cause no synchronization to take place and are non-blocking.
They simply free the resources used to create the virtual circuit.
.SH EXAMPLE USAGE
This is an example code showing how a virtual circuit is used to send
an array of 4-byte floating point numbers from node n1 to node n0,
using event 6 and type 0.
Error codes are not checked in order to keep the code simple.
.PP
The sender on node n1 executes the following code:
.PP
.ta 1.5i
.nf
float4 data[5];
struct nmsg header;
header.nh_node = 0;
header.nh_event = 6;
header.nh_type = 0;
psendopen(&header);
header.nh_msg = (char *) data;
header.nh_length = 5 * sizeof(float4);
header.nh_flags = DFLT4MSG;
psend(&header);
psendclose(&header);
.fi
.PP
The receiving process on node n0, not knowing how many floating point
numbers are going to be sent, sets a maximum limit of 20.
.I precv()
modifies the value of
.I nh_length
in the header to indicate the length of the received message, i.e. four
times the number of numbers sent.
The receiver executes the following code:
.PP
.ta 1.5i
.nf
float4 indata[20];
int4 num;
struct nmsg header;
header.nh_event = 6;
header.nh_type = 0;
precvopen(&header);
header.nh_msg = (char *) indata;
header.nh_length = 20 * sizeof(float4);
header.nh_flags = DFLT4MSG;
precv(&header);
num = header.nh_length / 4;
precvclose(&header);
.fi
.SH ERRORS
.TP 16
EFULL
The virtual circuit table is full.
.TP
EINVAL
The virtual circuit is invalid.
If returned by
.I psendopen()
or
.I precvopen()
this means the virtual circuit is already open.
Otherwise it means the virtual circuit does not exist.
.SH LIMITATIONS
In the current implementation, the sender and receiver have to be on
different nodes.
The factory default size of the virtual circuit table is 67.
.SH SEE ALSO
nsend(2)
|
