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
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
|
###############################################################################
# #
# TakTuk, a middleware for adaptive large scale parallel remote executions #
# deployment. Perl implementation, copyright(C) 2006 Guillaume Huard. #
# #
# This program is free software; you can redistribute it and/or modify #
# it under the terms of the GNU General Public License as published by #
# the Free Software Foundation; either version 2 of the License, or #
# (at your option) any later version. #
# #
# This program is distributed in the hope that it will be useful, #
# but WITHOUT ANY WARRANTY; without even the implied warranty of #
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the #
# GNU General Public License for more details. #
# #
# You should have received a copy of the GNU General Public License #
# along with this program; if not, write to the Free Software #
# Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA #
# #
# Contact: Guillaume.Huard@imag.fr #
# Laboratoire LIG - ENSIMAG - Antenne de Montbonnot #
# 51 avenue Jean Kuntzmann #
# 38330 Montbonnot Saint Martin #
# FRANCE #
# #
###############################################################################
=pod TakTuk communication layer interface documentation (C interface)
=begin html
<center><h1>USER MANUAL</h1></center>
=end html
=head1 NAME
taktuk - Interface library to C<taktuk(1)> communication facilities
=head1 SYNOPSIS
#include <taktuk.h>
const char *taktuk_error_msg(int msg_code);
int taktuk_init_threads();
int taktuk_leave_threads();
int taktuk_get(const char *field, unsigned long *result);
int taktuk_multi_send(const char *dest, const char *target,
const void *buffer, size_t length);
int taktuk_multi_sendv(const char *dest, const char *target,
const struct iovec *iov, int iovcnt);
int taktuk_send(unsigned long dest, unsigned long target,
const void *buffer, size_t length);
int taktuk_sendv(unsigned long dest, unsigned long target,
const struct iovec *iov, int iovcnt);
int taktuk_recv(unsigned long *from, void *buffer, size_t *length,
struct timeval *timeout);
int taktuk_recvv(unsigned long *from, const struct iovec *iov,
int iovcnt, struct timeval *timeout);
int taktuk_wait_message(unsigned long *from, size_t *size,
struct timeval *timeout);
int taktuk_read( void *buffer, size_t length );
int taktuk_readv( const struct iovec *iov, int iovcnt );
=head1 DESCRIPTION
The B<TakTuk> communication layer interface library provides a way for programs
executed using the C<taktuk(1)> command to exchange data. It is based on a
simple send/receive model using multicast-like sends and optionally timeouted
receives. This is only designed to be a control facility, in particular this
is not a high performance communication library.
Any program using B<TakTuk> C communication interface has to link his program
to the C<taktuk> and C<pthread> libraries (the C<taktuk> library is provided
with the distribution).
Headers for communication functions and constants definitions can be found in
C<taktuk.h> also provided with the distribution.
The communication functions are:
=head2 miscellaneous functions
=over
=item B<int taktuk_init_threads>B<();>
=item B<int taktuk_leave_threads>B<();>
functions to be called once in the process respectively before threads creation
and after threads destruction if you want B<TakTuk> C interface to be
thread-safe.
Nevertheless, notice that, because of the way B<TakTuk> is implemented, the
handling of C<recv> functions in several threads is completely sequentialized.
This is especially important regarding timeouts: if a timeout is given to a
C<recv> function, it will only be started at the calling thread's turn. In
other words, issuing multiple timeouted C<recv> in several threads of the same
process might result in timeouts longer that expected (they become at most the
sum of all pending C<recv> timeouts).
=item B<int taktuk_get(const char *field, unsigned long *result);>
gets some information from B<TakTuk> and places it into result. Currently
available information are "target", "rank", "count", "father", "child_min" and
"child_max". This is a better way to get these information than environment
variables as its takes into account renumbering that might occur after process
spawn.
=back
=head2 multicast send functions
=over
=item B<int taktuk_multi_send(const char *dest, const char *target, const void *buffer, size_t length);>
=item B<int taktuk_multi_sendv(const char *dest, const char *target, const struct iovec *iov, int iovcnt);>
C<taktuk_multi_send> sends the content of C<buffer> made of C<length> bytes to
the set of target processes C<target> present on the set of destinations
C<dest> (nul terminated characters strings, see C<taktuk(1)> for information
about set specifications for destination hosts and target processes).
C<taktuk_multi_sendv> is the vector variant of C<taktuk_multi_send> (similar to
C<writev> system function).
=back
=head2 single host send/recv functions
=over
=item B<int taktuk_send(unsigned long dest, unsigned long target, const void *buffer, size_t length);>
=item B<int taktuk_sendv(unsigned long dest, unsigned long target, const struct iovec *iov, int iovcnt);>
sends the content of C<buffer> made of C<length> bytes to process C<target> on
the host C<dest> (see C<taktuk(1)> for more information about target
processes). In this case, the target value might also be
TAKTUK_TARGET_ANY to target the first process performing a C<recv>,
TAKTUK_TARGET_ALL to target all processes, or TAKTUK_TARGET_OUTPUT to target
the C<message> stream rather than a process. C<taktuk_sendv> is the vector
variant of C<taktuk_send> (similar to C<writev> system function).
=item B<int taktuk_recv(unsigned long *from, void *buffer, size_t *length, struct timeval *timeout);>
=item B<int taktuk_recvv(unsigned long *from, const struct iovec *iov, int iovcnt, struct timeval *timeout);>
blocks until the reception of a message. If a regular message is received,
C<taktuk_recv> sets the value of its arguments: C<from> to the logical number
of the sender, C<buffer> to the data received which is made of
C<length> bytes. If timeout is not NULL, C<taktuk_recv()> might receive a
timeout notification. In this case, C<taktuk_recv()> returns the TAKTUK_ETMOUT
error code.
C<taktuk_recvv> is the vector variant of C<taktuk_recv> (similar to
C<readv> system function).
WARNING: the buffer size should be sufficient to receive all the data of the
matching send. If this is not the case, the program is likely to end up
abruptly with a segmentation fault.
=back
=head2 low-level recv functions
=over
=item B<int taktuk_wait_message(unsigned long* from, size_t *size, struct timeval *timeout);>
=item B<int taktuk_read (void* buffer, size_t length);>
=item B<int taktuk_readv(const struct iovec *iov, int iovcnt);>
C<taktuk_wait_message> waits for a taktuk message to be available and sets
C<from> to the logical number of the sender and C<size> to the size of the
received message.
It must be followed by a call to either C<taktuk_read> or C<taktuk_readv> to
read the data (using the size given by C<taktuk_wait_message>).
As other B<TakTuk> receive functions, this function might return the
TAKTUK_ETMOUT error code if C<timeout> is not NULL and expires before the
reception.
If you don't know in advance the size of the data being sent to you, you can
use these lower level functions. Actually, C<taktuk_recv> is equivalent to a
call to C<taktuk_wait_message> followed by errors checks on buffer size and a
call to C<taktuk_read>. This is the same for C<taktuk_recvv>.
=back
=head1 RETURN VALUE
When an error occur, all of these functions return one of the following numeric
error code. A textual description of the error is provided by the function
C<taktuk_error_msg()> that takes the error code as an argument.
Error codes are the following :
=over
=item TAKTUK_ESWRIT
a call to C<write(2)> failed. The code should be accessible using C<errno>.
=item TAKTUK_EFCLSD
the communication channel to the B<TakTuk> engine has been closed. This
typically occur when shutting down the logical network (using Ctrl-C on root
node for instance).
=item TAKTUK_ESREAD (receives only)
a call to C<read(2)> failed. The code should be accessible using C<errno>.
=item TAKTUK_ETMOUT (receives only)
The call to C<taktuk_recv()> (or its vectorized equivalent) or to
C<taktuk_wait_message> timeouted. This only occur when giving a non nul
C<timeout> value to these functions.
=item TAKTUK_EALLOC
An internal memory allocation failure occurred.
=item TAKTUK_EIBUFF
A buffer of incorrect size has been given to store all the data read by a
receive function.
=item TAKTUK_ENOCON
The connector communication channels have not been found. This typically occur
when launching a B<TakTuk> program without using B<TakTuk>.
=item TAKTUK_EINVAL (get only)
The field given to C<taktuk_get> is not a valid B<TakTuk> field.
=item TAKTUK_EMTXNM (init threads only)
No memory to allocate a new mutex
=item TAKTUK_EMTXAG (init threads only)
Resources temporarily unavailable for new mutex allocation.
=back
Other error codes are internal B<TakTuk> errors which should strongly suggest a
bug in B<TakTuk>. They have also a textual description that is returned by
C<taktuk_error_msg>.
=head1 SEE ALSO
C<tatkuk(1)>, C<TakTuk(3)>, C<TakTuk::Pilot(3)>
=head1 AUTHOR
The original concept of B<TakTuk> has been proposed by Cyrille Martin in his PhD thesis. People involved in this work include Jacques Briat, Olivier Richard, Thierry Gautier and Guillaume Huard.
The author of the version 3 (perl version) and current maintainer of the package is Guillaume Huard.
=head1 COPYRIGHT
The C<taktukcomm> communication interface library is provided under the terms
of the GNU General Public License version 2 or later.
=cut
|
