1 /*
2 * Copyright (C) Mellanox Technologies Ltd. 2001-2014. ALL RIGHTS RESERVED.
3 * Copyright (C) UT-Battelle, LLC. 2014-2017. ALL RIGHTS RESERVED.
4 * Copyright (C) ARM Ltd. 2016-2017. ALL RIGHTS RESERVED.
5 * Copyright (C) Los Alamos National Security, LLC. 2018 ALL RIGHTS RESERVED.
6 * See file LICENSE for terms.
7 */
8
9 #ifndef UCP_H_
10 #define UCP_H_
11
12 #include <ucp/api/ucp_def.h>
13 #include <ucp/api/ucp_compat.h>
14 #include <ucp/api/ucp_version.h>
15 #include <ucs/type/thread_mode.h>
16 #include <ucs/type/cpu_set.h>
17 #include <ucs/config/types.h>
18 #include <ucs/sys/compiler_def.h>
19 #include <stdio.h>
20 #include <sys/types.h>
21
22 BEGIN_C_DECLS
23
24 /**
25 * @defgroup UCP_API Unified Communication Protocol (UCP) API
26 * @{
27 * This section describes UCP API.
28 * @}
29 */
30
31 /**
32 * @defgroup UCP_CONTEXT UCP Application Context
33 * @ingroup UCP_API
34 * @{
35 * Application context is a primary concept of UCP design which
36 * provides an isolation mechanism, allowing resources associated
37 * with the context to separate or share network communication context
38 * across multiple instances of applications.
39 *
40 * This section provides a detailed description of this concept and
41 * routines associated with it.
42 *
43 * @}
44 */
45
46
47 /**
48 * @defgroup UCP_WORKER UCP Worker
49 * @ingroup UCP_API
50 * @{
51 * UCP Worker routines
52 * @}
53 */
54
55
56 /**
57 * @defgroup UCP_MEM UCP Memory routines
58 * @ingroup UCP_API
59 * @{
60 * UCP Memory routines
61 * @}
62 */
63
64
65 /**
66 * @defgroup UCP_WAKEUP UCP Wake-up routines
67 * @ingroup UCP_API
68 * @{
69 * UCP Wake-up routines
70 * @}
71 */
72
73
74 /**
75 * @defgroup UCP_ENDPOINT UCP Endpoint
76 * @ingroup UCP_API
77 * @{
78 * UCP Endpoint routines
79 * @}
80 */
81
82
83 /**
84 * @defgroup UCP_COMM UCP Communication routines
85 * @ingroup UCP_API
86 * @{
87 * UCP Communication routines
88 * @}
89 */
90
91
92 /**
93 * @defgroup UCP_CONFIG UCP Configuration
94 * @ingroup UCP_API
95 * @{
96 * This section describes routines for configuration
97 * of the UCP network layer
98 * @}
99 */
100
101
102 /**
103 * @defgroup UCP_DATATYPE UCP Data type routines
104 * @ingroup UCP_API
105 * @{
106 * UCP Data type routines
107 * @}
108 */
109
110
111 /**
112 * @ingroup UCP_CONTEXT
113 * @brief UCP context parameters field mask.
114 *
115 * The enumeration allows specifying which fields in @ref ucp_params_t are
116 * present. It is used to enable backward compatibility support.
117 */
118 enum ucp_params_field {
119 UCP_PARAM_FIELD_FEATURES = UCS_BIT(0), /**< features */
120 UCP_PARAM_FIELD_REQUEST_SIZE = UCS_BIT(1), /**< request_size */
121 UCP_PARAM_FIELD_REQUEST_INIT = UCS_BIT(2), /**< request_init */
122 UCP_PARAM_FIELD_REQUEST_CLEANUP = UCS_BIT(3), /**< request_cleanup */
123 UCP_PARAM_FIELD_TAG_SENDER_MASK = UCS_BIT(4), /**< tag_sender_mask */
124 UCP_PARAM_FIELD_MT_WORKERS_SHARED = UCS_BIT(5), /**< mt_workers_shared */
125 UCP_PARAM_FIELD_ESTIMATED_NUM_EPS = UCS_BIT(6), /**< estimated_num_eps */
126 UCP_PARAM_FIELD_ESTIMATED_NUM_PPN = UCS_BIT(7) /**< estimated_num_ppn */
127 };
128
129
130 /**
131 * @ingroup UCP_CONTEXT
132 * @brief UCP configuration features
133 *
134 * The enumeration list describes the features supported by UCP. An
135 * application can request the features using @ref ucp_params_t "UCP parameters"
136 * during @ref ucp_init "UCP initialization" process.
137 */
138 enum ucp_feature {
139 UCP_FEATURE_TAG = UCS_BIT(0), /**< Request tag matching
140 support */
141 UCP_FEATURE_RMA = UCS_BIT(1), /**< Request remote memory
142 access support */
143 UCP_FEATURE_AMO32 = UCS_BIT(2), /**< Request 32-bit atomic
144 operations support */
145 UCP_FEATURE_AMO64 = UCS_BIT(3), /**< Request 64-bit atomic
146 operations support */
147 UCP_FEATURE_WAKEUP = UCS_BIT(4), /**< Request interrupt
148 notification support */
149 UCP_FEATURE_STREAM = UCS_BIT(5), /**< Request stream support */
150 UCP_FEATURE_AM = UCS_BIT(6) /**< Request Active Message
151 support */
152 };
153
154
155 /**
156 * @ingroup UCP_WORKER
157 * @brief UCP worker parameters field mask.
158 *
159 * The enumeration allows specifying which fields in @ref ucp_worker_params_t are
160 * present. It is used to enable backward compatibility support.
161 */
162 enum ucp_worker_params_field {
163 UCP_WORKER_PARAM_FIELD_THREAD_MODE = UCS_BIT(0), /**< UCP thread mode */
164 UCP_WORKER_PARAM_FIELD_CPU_MASK = UCS_BIT(1), /**< Worker's CPU bitmap */
165 UCP_WORKER_PARAM_FIELD_EVENTS = UCS_BIT(2), /**< Worker's events bitmap */
166 UCP_WORKER_PARAM_FIELD_USER_DATA = UCS_BIT(3), /**< User data */
167 UCP_WORKER_PARAM_FIELD_EVENT_FD = UCS_BIT(4) /**< External event file
168 descriptor */
169 };
170
171
172 /**
173 * @ingroup UCP_WORKER
174 * @brief UCP listener parameters field mask.
175 *
176 * The enumeration allows specifying which fields in @ref ucp_listener_params_t
177 * are present. It is used to enable backward compatibility support.
178 */
179 enum ucp_listener_params_field {
180 /**
181 * Sock address and length.
182 */
183 UCP_LISTENER_PARAM_FIELD_SOCK_ADDR = UCS_BIT(0),
184
185 /**
186 * User's callback and argument for handling the creation of an endpoint.
187 * */
188 UCP_LISTENER_PARAM_FIELD_ACCEPT_HANDLER = UCS_BIT(1),
189
190 /**< User's callback and argument for handling the incoming connection
191 * request. */
192 UCP_LISTENER_PARAM_FIELD_CONN_HANDLER = UCS_BIT(2)
193 };
194
195
196 /**
197 * @ingroup UCP_WORKER
198 * @brief UCP worker address flags.
199 *
200 * The enumeration list describes possible UCP worker address flags, indicating
201 * what needs to be included to the worker address returned by
202 * @ref ucp_worker_query "ucp_worker_query()" routine.
203 */
204 typedef enum {
205
206 /**< Pack addresses of network devices only. Using such shortened addresses
207 * for the remote node peers will reduce the amount of wireup data being
208 * exchanged during connection establishment phase. */
209 UCP_WORKER_ADDRESS_FLAG_NET_ONLY = UCS_BIT(0)
210 } ucp_worker_address_flags_t;
211
212
213 /**
214 * @ingroup UCP_ENDPOINT
215 * @brief UCP endpoint parameters field mask.
216 *
217 * The enumeration allows specifying which fields in @ref ucp_ep_params_t are
218 * present. It is used to enable backward compatibility support.
219 */
220 enum ucp_ep_params_field {
221 UCP_EP_PARAM_FIELD_REMOTE_ADDRESS = UCS_BIT(0), /**< Address of remote
222 peer */
223 UCP_EP_PARAM_FIELD_ERR_HANDLING_MODE = UCS_BIT(1), /**< Error handling mode.
224 @ref ucp_err_handling_mode_t */
225 UCP_EP_PARAM_FIELD_ERR_HANDLER = UCS_BIT(2), /**< Handler to process
226 transport level errors */
227 UCP_EP_PARAM_FIELD_USER_DATA = UCS_BIT(3), /**< User data pointer */
228 UCP_EP_PARAM_FIELD_SOCK_ADDR = UCS_BIT(4), /**< Socket address field */
229 UCP_EP_PARAM_FIELD_FLAGS = UCS_BIT(5), /**< Endpoint flags */
230 UCP_EP_PARAM_FIELD_CONN_REQUEST = UCS_BIT(6) /**< Connection request field */
231 };
232
233
234 /**
235 * @ingroup UCP_ENDPOINT
236 * @brief UCP endpoint parameters flags.
237 *
238 * The enumeration list describes the endpoint's parameters flags supported by
239 * @ref ucp_ep_create() function.
240 */
241 enum ucp_ep_params_flags_field {
242 UCP_EP_PARAMS_FLAGS_CLIENT_SERVER = UCS_BIT(0), /**< Using a client-server
243 connection establishment
244 mechanism.
245 @ref ucs_sock_addr_t
246 sockaddr field
247 must be provided and
248 contain the address
249 of the remote peer */
250 UCP_EP_PARAMS_FLAGS_NO_LOOPBACK = UCS_BIT(1) /**< Avoid connecting the
251 endpoint to itself when
252 connecting the endpoint
253 to the same worker it
254 was created on.
255 Affects protocols which
256 send to a particular
257 remote endpoint, for
258 example stream */
259 };
260
261
262 /**
263 * @ingroup UCP_ENDPOINT
264 * @brief Close UCP endpoint modes.
265 *
266 * The enumeration is used to specify the behavior of @ref ucp_ep_close_nbx.
267 */
268 typedef enum {
269 UCP_EP_CLOSE_FLAG_FORCE = UCS_BIT(0) /**< @ref ucp_ep_close_nbx releases
270 the endpoint without any
271 confirmation from the peer. All
272 outstanding requests will be
273 completed with
274 @ref UCS_ERR_CANCELED error.
275 @note This mode may cause
276 transport level errors on remote
277 side, so it requires set
278 @ref UCP_ERR_HANDLING_MODE_PEER
279 for all endpoints created on
280 both (local and remote) sides to
281 avoid undefined behavior. If this
282 flag is not set then
283 @ref ucp_ep_close_nbx schedules
284 flushes on all outstanding
285 operations. */
286 } ucp_ep_close_flags_t;
287
288
289 /**
290 * @ingroup UCP_ENDPOINT
291 * @brief Close UCP endpoint modes.
292 *
293 * The enumeration is used to specify the behavior of @ref ucp_ep_close_nb.
294 */
295 enum ucp_ep_close_mode {
296 UCP_EP_CLOSE_MODE_FORCE = 0, /**< @ref ucp_ep_close_nb releases
297 the endpoint without any
298 confirmation from the peer. All
299 outstanding requests will be
300 completed with
301 @ref UCS_ERR_CANCELED error.
302 @note This mode may cause
303 transport level errors on remote
304 side, so it requires set
305 @ref UCP_ERR_HANDLING_MODE_PEER
306 for all endpoints created on
307 both (local and remote) sides to
308 avoid undefined behavior. */
309 UCP_EP_CLOSE_MODE_FLUSH = 1 /**< @ref ucp_ep_close_nb schedules
310 flushes on all outstanding
311 operations. */
312 };
313
314
315 /**
316 * @ingroup UCP_MEM
317 * @brief UCP memory mapping parameters field mask.
318 *
319 * The enumeration allows specifying which fields in @ref ucp_mem_map_params_t are
320 * present. It is used to enable backward compatibility support.
321 */
322 enum ucp_mem_map_params_field {
323 UCP_MEM_MAP_PARAM_FIELD_ADDRESS = UCS_BIT(0), /**< Address of the memory that
324 will be used in the
325 @ref ucp_mem_map routine. */
326 UCP_MEM_MAP_PARAM_FIELD_LENGTH = UCS_BIT(1), /**< The size of memory that
327 will be allocated or
328 registered in the
329 @ref ucp_mem_map routine.*/
330 UCP_MEM_MAP_PARAM_FIELD_FLAGS = UCS_BIT(2) /**< Allocation flags. */
331 };
332
333 /**
334 * @ingroup UCP_MEM
335 * @brief UCP memory advice parameters field mask.
336 *
337 * The enumeration allows specifying which fields in @ref ucp_mem_advise_params_t are
338 * present. It is used to enable backward compatibility support.
339 */
340 enum ucp_mem_advise_params_field {
341 UCP_MEM_ADVISE_PARAM_FIELD_ADDRESS = UCS_BIT(0), /**< Address of the memory */
342 UCP_MEM_ADVISE_PARAM_FIELD_LENGTH = UCS_BIT(1), /**< The size of memory */
343 UCP_MEM_ADVISE_PARAM_FIELD_ADVICE = UCS_BIT(2) /**< Advice on memory usage */
344 };
345
346
347 /**
348 * @ingroup UCP_CONTEXT
349 * @brief UCP context attributes field mask.
350 *
351 * The enumeration allows specifying which fields in @ref ucp_context_attr_t are
352 * present. It is used to enable backward compatibility support.
353 */
354 enum ucp_context_attr_field {
355 UCP_ATTR_FIELD_REQUEST_SIZE = UCS_BIT(0), /**< UCP request size */
356 UCP_ATTR_FIELD_THREAD_MODE = UCS_BIT(1) /**< UCP context thread flag */
357 };
358
359
360 /**
361 * @ingroup UCP_WORKER
362 * @brief UCP worker attributes field mask.
363 *
364 * The enumeration allows specifying which fields in @ref ucp_worker_attr_t are
365 * present. It is used to enable backward compatibility support.
366 */
367 enum ucp_worker_attr_field {
368 UCP_WORKER_ATTR_FIELD_THREAD_MODE = UCS_BIT(0), /**< UCP thread mode */
369 UCP_WORKER_ATTR_FIELD_ADDRESS = UCS_BIT(1), /**< UCP address */
370 UCP_WORKER_ATTR_FIELD_ADDRESS_FLAGS = UCS_BIT(2) /**< UCP address flags */
371 };
372
373
374 /**
375 * @ingroup UCP_WORKER
376 * @brief UCP listener attributes field mask.
377 *
378 * The enumeration allows specifying which fields in @ref ucp_listener_attr_t are
379 * present. It is used to enable backward compatibility support.
380 */
381 enum ucp_listener_attr_field {
382 UCP_LISTENER_ATTR_FIELD_SOCKADDR = UCS_BIT(0) /**< Sockaddr used for listening */
383 };
384
385
386 /**
387 * @ingroup UCP_WORKER
388 * @brief UCP listener's connection request attributes field mask.
389 *
390 * The enumeration allows specifying which fields in @ref ucp_conn_request_attr_t
391 * are present. It is used to enable backward compatibility support.
392 */
393 enum ucp_conn_request_attr_field {
394 UCP_CONN_REQUEST_ATTR_FIELD_CLIENT_ADDR = UCS_BIT(0) /**< Client's address */
395 };
396
397
398 /**
399 * @ingroup UCP_DATATYPE
400 * @brief UCP data type classification
401 *
402 * The enumeration list describes the datatypes supported by UCP.
403 */
404 enum ucp_dt_type {
405 UCP_DATATYPE_CONTIG = 0, /**< Contiguous datatype */
406 UCP_DATATYPE_STRIDED = 1, /**< Strided datatype */
407 UCP_DATATYPE_IOV = 2, /**< Scatter-gather list with multiple pointers */
408 UCP_DATATYPE_GENERIC = 7, /**< Generic datatype with
409 user-defined pack/unpack routines */
410 UCP_DATATYPE_SHIFT = 3, /**< Number of bits defining
411 the datatype classification */
412 UCP_DATATYPE_CLASS_MASK = UCS_MASK(UCP_DATATYPE_SHIFT) /**< Data-type class
413 mask */
414 };
415
416
417 /**
418 * @ingroup UCP_MEM
419 * @brief UCP memory mapping flags.
420 *
421 * The enumeration list describes the memory mapping flags supported by @ref
422 * ucp_mem_map() function.
423 */
424 enum {
425 UCP_MEM_MAP_NONBLOCK = UCS_BIT(0), /**< Complete the mapping faster, possibly by
426 not populating the pages in the mapping
427 up-front, and mapping them later when
428 they are accessed by communication
429 routines. */
430 UCP_MEM_MAP_ALLOCATE = UCS_BIT(1), /**< Identify requirement for allocation,
431 if passed address is not a null-pointer
432 then it will be used as a hint or direct
433 address for allocation. */
434 UCP_MEM_MAP_FIXED = UCS_BIT(2) /**< Don't interpret address as a hint:
435 place the mapping at exactly that
436 address. The address must be a multiple
437 of the page size. */
438 };
439
440
441 /**
442 * @ingroup UCP_WORKER
443 * @brief Flags for a UCP Active Message callback.
444 *
445 * Flags that indicate how to handle UCP Active Messages
446 * Currently only UCP_AM_FLAG_WHOLE_MSG is supported,
447 * which indicates the entire message is handled in one
448 * callback.
449 */
450 enum ucp_am_cb_flags {
451 UCP_AM_FLAG_WHOLE_MSG = UCS_BIT(0)
452 };
453
454
455 /**
456 * @ingroup UCP_WORKER
457 * @brief Flags for sending a UCP Active Message.
458 *
459 * Flags dictate the behavior of ucp_am_send_nb
460 * currently the only flag tells UCP to pass in
461 * the sending endpoint to the call
462 * back so a reply can be defined.
463 */
464 enum ucp_send_am_flags {
465 UCP_AM_SEND_REPLY = UCS_BIT(0)
466 };
467
468
469 /**
470 * @ingroup UCP_ENDPOINT
471 * @brief Descriptor flags for Active Message callback.
472 *
473 * In a callback, if flags is set to UCP_CB_PARAM_FLAG_DATA in
474 * a callback then data was allocated, so if UCS_INPROGRESS is
475 * returned from the callback, the data parameter will persist
476 * and the user has to call @ref ucp_am_data_release when data is
477 * no longer needed.
478 */
479 enum ucp_cb_param_flags {
480 UCP_CB_PARAM_FLAG_DATA = UCS_BIT(0)
481 };
482
483
484 /**
485 * @ingroup UCP_COMM
486 * @brief Atomic operation requested for ucp_atomic_post
487 *
488 * This enumeration defines which atomic memory operation should be
489 * performed by the ucp_atomic_post family of fuctions. All of these are
490 * non-fetching atomics and will not result in a request handle.
491 */
492 typedef enum {
493 UCP_ATOMIC_POST_OP_ADD, /**< Atomic add */
494 UCP_ATOMIC_POST_OP_AND, /**< Atomic and */
495 UCP_ATOMIC_POST_OP_OR, /**< Atomic or */
496 UCP_ATOMIC_POST_OP_XOR, /**< Atomic xor */
497 UCP_ATOMIC_POST_OP_LAST
498 } ucp_atomic_post_op_t;
499
500
501 /**
502 * @ingroup UCP_COMM
503 * @brief Atomic operation requested for ucp_atomic_fetch
504 *
505 * This enumeration defines which atomic memory operation should be performed
506 * by the ucp_atomic_fetch family of functions. All of these functions
507 * will fetch data from the remote node.
508 */
509 typedef enum {
510 UCP_ATOMIC_FETCH_OP_FADD, /**< Atomic Fetch and add */
511 UCP_ATOMIC_FETCH_OP_SWAP, /**< Atomic swap */
512 UCP_ATOMIC_FETCH_OP_CSWAP, /**< Atomic conditional swap */
513 UCP_ATOMIC_FETCH_OP_FAND, /**< Atomic Fetch and and */
514 UCP_ATOMIC_FETCH_OP_FOR, /**< Atomic Fetch and or */
515 UCP_ATOMIC_FETCH_OP_FXOR, /**< Atomic Fetch and xor */
516 UCP_ATOMIC_FETCH_OP_LAST
517 } ucp_atomic_fetch_op_t;
518
519
520 /**
521 * @ingroup UCP_COMM
522 * @brief Atomic operation requested for ucp_atomic_op_nbx
523 *
524 * This enumeration defines which atomic memory operation should be
525 * performed by the @ref ucp_atomic_op_nbx routine.
526 */
527 typedef enum {
528 UCP_ATOMIC_OP_ADD, /**< Atomic add */
529 UCP_ATOMIC_OP_SWAP, /**< Atomic swap */
530 UCP_ATOMIC_OP_CSWAP, /**< Atomic conditional swap */
531 UCP_ATOMIC_OP_AND, /**< Atomic and */
532 UCP_ATOMIC_OP_OR, /**< Atomic or */
533 UCP_ATOMIC_OP_XOR, /**< Atomic xor */
534 UCP_ATOMIC_OP_LAST
535 } ucp_atomic_op_t;
536
537
538 /**
539 * @ingroup UCP_COMM
540 * @brief Flags to define behavior of @ref ucp_stream_recv_nb function
541 *
542 * This enumeration defines behavior of @ref ucp_stream_recv_nb function.
543 */
544 typedef enum {
545 UCP_STREAM_RECV_FLAG_WAITALL = UCS_BIT(0) /**< This flag requests that
546 the operation will not be
547 completed until all
548 requested data is received
549 and placed in the user
550 buffer. */
551 } ucp_stream_recv_flags_t;
552
553
554 /**
555 * @ingroup UCP_COMM
556 * @brief UCP operation fields and flags
557 *
558 * The enumeration allows specifying which fields in @ref ucp_request_param_t are
559 * present and operation flags are used. It is used to enable backward
560 * compatibility support.
561 */
562 typedef enum {
563 UCP_OP_ATTR_FIELD_REQUEST = UCS_BIT(0), /**< request field */
564 UCP_OP_ATTR_FIELD_CALLBACK = UCS_BIT(1), /**< cb field */
565 UCP_OP_ATTR_FIELD_USER_DATA = UCS_BIT(2), /**< user_data field */
566 UCP_OP_ATTR_FIELD_DATATYPE = UCS_BIT(3), /**< datatype field */
567 UCP_OP_ATTR_FIELD_FLAGS = UCS_BIT(4), /**< operation-specific flags */
568 UCP_OP_ATTR_FIELD_REPLY_BUFFER = UCS_BIT(5), /**< reply_buffer field */
569
570 UCP_OP_ATTR_FLAG_NO_IMM_CMPL = UCS_BIT(16), /**< deny immediate completion */
571 UCP_OP_ATTR_FLAG_FAST_CMPL = UCS_BIT(17), /**< expedite local completion,
572 even if it delays remote
573 data delivery. Note for
574 implementer: this option
575 can disable zero copy
576 and/or rendezvous protocols
577 which require
578 synchronization with the
579 remote peer before releasing
580 the local send buffer */
581 UCP_OP_ATTR_FLAG_FORCE_IMM_CMPL = UCS_BIT(18) /**< force immediate complete
582 operation, fail if the
583 operation cannot be
584 completed immediately */
585 } ucp_op_attr_t;
586
587
588 /**
589 * @ingroup UCP_DATATYPE
590 * @brief Generate an identifier for contiguous data type.
591 *
592 * This macro creates an identifier for contiguous datatype that is defined by
593 * the size of the basic element.
594 *
595 * @param [in] _elem_size Size of the basic element of the type.
596 *
597 * @return Data-type identifier.
598 *
599 * @note In case of partial receive, the buffer will be filled with integral
600 * count of elements.
601 */
602 #define ucp_dt_make_contig(_elem_size) \
603 (((ucp_datatype_t)(_elem_size) << UCP_DATATYPE_SHIFT) | UCP_DATATYPE_CONTIG)
604
605
606 /**
607 * @ingroup UCP_DATATYPE
608 * @brief Generate an identifier for Scatter-gather IOV data type.
609 *
610 * This macro creates an identifier for datatype of scatter-gather list
611 * with multiple pointers
612 *
613 * @return Data-type identifier.
614 *
615 * @note In case of partial receive, @ref ucp_dt_iov_t::buffer can be filled
616 * with any number of bytes according to its @ref ucp_dt_iov_t::length.
617 */
618 #define ucp_dt_make_iov() (UCP_DATATYPE_IOV)
619
620
621 /**
622 * @ingroup UCP_DATATYPE
623 * @brief Structure for scatter-gather I/O.
624 *
625 * This structure is used to specify a list of buffers which can be used
626 * within a single data transfer function call.
627 *
628 * @note If @a length is zero, the memory pointed to by @a buffer
629 * will not be accessed. Otherwise, @a buffer must point to valid memory.
630 */
631 typedef struct ucp_dt_iov {
632 void *buffer; /**< Pointer to a data buffer */
633 size_t length; /**< Length of the @a buffer in bytes */
634 } ucp_dt_iov_t;
635
636
637 /**
638 * @ingroup UCP_DATATYPE
639 * @brief UCP generic data type descriptor
640 *
641 * This structure provides a generic datatype descriptor that
642 * is used for definition of application defined datatypes.
643
644 * Typically, the descriptor is used for an integration with datatype
645 * engines implemented within MPI and SHMEM implementations.
646 *
647 * @note In case of partial receive, any amount of received data is acceptable
648 * which matches buffer size.
649 */
650 typedef struct ucp_generic_dt_ops {
651
652 /**
653 * @ingroup UCP_DATATYPE
654 * @brief Start a packing request.
655 *
656 * The pointer refers to application defined start-to-pack routine. It will
657 * be called from the @ref ucp_tag_send_nb routine.
658 *
659 * @param [in] context User-defined context.
660 * @param [in] buffer Buffer to pack.
661 * @param [in] count Number of elements to pack into the buffer.
662 *
663 * @return A custom state that is passed to the following
664 * @ref ucp_generic_dt_ops::pack "pack()" routine.
665 */
666 void* (*start_pack)(void *context, const void *buffer, size_t count);
667
668 /**
669 * @ingroup UCP_DATATYPE
670 * @brief Start an unpacking request.
671 *
672 * The pointer refers to application defined start-to-unpack routine. It will
673 * be called from the @ref ucp_tag_recv_nb routine.
674 *
675 * @param [in] context User-defined context.
676 * @param [in] buffer Buffer to unpack to.
677 * @param [in] count Number of elements to unpack in the buffer.
678 *
679 * @return A custom state that is passed later to the following
680 * @ref ucp_generic_dt_ops::unpack "unpack()" routine.
681 */
682 void* (*start_unpack)(void *context, void *buffer, size_t count);
683
684 /**
685 * @ingroup UCP_DATATYPE
686 * @brief Get the total size of packed data.
687 *
688 * The pointer refers to user defined routine that returns the size of data
689 * in a packed format.
690 *
691 * @param [in] state State as returned by
692 * @ref ucp_generic_dt_ops::start_pack
693 * "start_pack()" routine.
694 *
695 * @return The size of the data in a packed form.
696 */
697 size_t (*packed_size)(void *state);
698
699 /**
700 * @ingroup UCP_DATATYPE
701 * @brief Pack data.
702 *
703 * The pointer refers to application defined pack routine.
704 *
705 * @param [in] state State as returned by
706 * @ref ucp_generic_dt_ops::start_pack
707 * "start_pack()" routine.
708 * @param [in] offset Virtual offset in the output stream.
709 * @param [in] dest Destination to pack the data to.
710 * @param [in] max_length Maximal length to pack.
711 *
712 * @return The size of the data that was written to the destination buffer.
713 * Must be less than or equal to @e max_length.
714 */
715 size_t (*pack) (void *state, size_t offset, void *dest, size_t max_length);
716
717 /**
718 * @ingroup UCP_DATATYPE
719 * @brief Unpack data.
720 *
721 * The pointer refers to application defined unpack routine.
722 *
723 * @param [in] state State as returned by
724 * @ref ucp_generic_dt_ops::start_unpack
725 * "start_unpack()" routine.
726 * @param [in] offset Virtual offset in the input stream.
727 * @param [in] src Source to unpack the data from.
728 * @param [in] length Length to unpack.
729 *
730 * @return UCS_OK or an error if unpacking failed.
731 */
732 ucs_status_t (*unpack)(void *state, size_t offset, const void *src, size_t length);
733
734 /**
735 * @ingroup UCP_DATATYPE
736 * @brief Finish packing/unpacking.
737 *
738 * The pointer refers to application defined finish routine.
739 *
740 * @param [in] state State as returned by
741 * @ref ucp_generic_dt_ops::start_pack
742 * "start_pack()"
743 * and
744 * @ref ucp_generic_dt_ops::start_unpack
745 * "start_unpack()"
746 * routines.
747 */
748 void (*finish)(void *state);
749 } ucp_generic_dt_ops_t;
750
751
752 /**
753 * @ingroup UCP_CONFIG
754 * @brief Tuning parameters for UCP library.
755 *
756 * The structure defines the parameters that are used for
757 * UCP library tuning during UCP library @ref ucp_init "initialization".
758 *
759 * @note UCP library implementation uses the @ref ucp_feature "features"
760 * parameter to optimize the library functionality that minimize memory
761 * footprint. For example, if the application does not require send/receive
762 * semantics UCP library may avoid allocation of expensive resources associated with
763 * send/receive queues.
764 */
765 typedef struct ucp_params {
766 /**
767 * Mask of valid fields in this structure, using bits from @ref ucp_params_field.
768 * Fields not specified in this mask will be ignored.
769 * Provides ABI compatibility with respect to adding new fields.
770 */
771 uint64_t field_mask;
772
773 /**
774 * UCP @ref ucp_feature "features" that are used for library
775 * initialization. It is recommended for applications only to request
776 * the features that are required for an optimal functionality
777 * This field must be specified.
778 */
779 uint64_t features;
780
781 /**
782 * The size of a reserved space in a non-blocking requests. Typically
783 * applications use this space for caching own structures in order to avoid
784 * costly memory allocations, pointer dereferences, and cache misses.
785 * For example, MPI implementation can use this memory for caching MPI
786 * descriptors
787 * This field defaults to 0 if not specified.
788 */
789 size_t request_size;
790
791 /**
792 * Pointer to a routine that is used for the request initialization.
793 * This function will be called only on the very first time a request memory
794 * is initialized, and may not be called again if a request is reused.
795 * If a request should be reset before the next reuse, it can be done before
796 * calling @ref ucp_request_free.
797 *
798 * @e NULL can be used if no such is function required, which is also the
799 * default if this field is not specified by @ref field_mask.
800 */
801 ucp_request_init_callback_t request_init;
802
803 /**
804 * Pointer to a routine that is responsible for final cleanup of the memory
805 * associated with the request. This routine may not be called every time a
806 * request is released. For some implementations, the cleanup call may be
807 * delayed and only invoked at @ref ucp_worker_destroy.
808 *
809 * @e NULL can be used if no such function is required, which is also the
810 * default if this field is not specified by @ref field_mask.
811 */
812 ucp_request_cleanup_callback_t request_cleanup;
813
814 /**
815 * Mask which specifies particular bits of the tag which can uniquely
816 * identify the sender (UCP endpoint) in tagged operations.
817 * This field defaults to 0 if not specified.
818 */
819 uint64_t tag_sender_mask;
820
821 /**
822 * This flag indicates if this context is shared by multiple workers
823 * from different threads. If so, this context needs thread safety
824 * support; otherwise, the context does not need to provide thread
825 * safety.
826 * For example, if the context is used by single worker, and that
827 * worker is shared by multiple threads, this context does not need
828 * thread safety; if the context is used by worker 1 and worker 2,
829 * and worker 1 is used by thread 1 and worker 2 is used by thread 2,
830 * then this context needs thread safety.
831 * Note that actual thread mode may be different from mode passed
832 * to @ref ucp_init. To get actual thread mode use
833 * @ref ucp_context_query.
834 */
835 int mt_workers_shared;
836
837 /**
838 * An optimization hint of how many endpoints will be created on this context.
839 * For example, when used from MPI or SHMEM libraries, this number will specify
840 * the number of ranks (or processing elements) in the job.
841 * Does not affect semantics, but only transport selection criteria and the
842 * resulting performance.
843 * The value can be also set by UCX_NUM_EPS environment variable. In such case
844 * it will override the number of endpoints set by @e estimated_num_eps
845 */
846 size_t estimated_num_eps;
847
848 /**
849 * An optimization hint for a single node. For example, when used from MPI or
850 * OpenSHMEM libraries, this number will specify the number of Processes Per
851 * Node (PPN) in the job. Does not affect semantics, only transport selection
852 * criteria and the resulting performance.
853 * The value can be also set by the UCX_NUM_PPN environment variable, which
854 * will override the number of endpoints set by @e estimated_num_ppn
855 */
856 size_t estimated_num_ppn;
857 } ucp_params_t;
858
859
860 /**
861 * @ingroup UCP_CONTEXT
862 * @brief Context attributes.
863 *
864 * The structure defines the attributes which characterize
865 * the particular context.
866 */
867 typedef struct ucp_context_attr {
868 /**
869 * Mask of valid fields in this structure, using bits from
870 * @ref ucp_context_attr_field.
871 * Fields not specified in this mask will be ignored.
872 * Provides ABI compatibility with respect to adding new fields.
873 */
874 uint64_t field_mask;
875
876 /**
877 * Size of UCP non-blocking request. When pre-allocated request is used
878 * (e.g. in @ref ucp_tag_recv_nbr) it should have enough space to fit
879 * UCP request data, which is defined by this value.
880 */
881 size_t request_size;
882
883 /**
884 * Thread safe level of the context. For supported thread levels please
885 * see @ref ucs_thread_mode_t.
886 */
887 ucs_thread_mode_t thread_mode;
888 } ucp_context_attr_t;
889
890
891 /**
892 * @ingroup UCP_WORKER
893 * @brief UCP worker attributes.
894 *
895 * The structure defines the attributes which characterize
896 * the particular worker.
897 */
898 typedef struct ucp_worker_attr {
899 /**
900 * Mask of valid fields in this structure, using bits from
901 * @ref ucp_worker_attr_field.
902 * Fields not specified in this mask will be ignored.
903 * Provides ABI compatibility with respect to adding new fields.
904 */
905 uint64_t field_mask;
906
907 /**
908 * Thread safe level of the worker.
909 */
910 ucs_thread_mode_t thread_mode;
911
912 /**
913 * Flags indicating requested details of the worker address.
914 * If @ref UCP_WORKER_ATTR_FIELD_ADDRESS_FLAGS bit is set in the field_mask,
915 * this value should be set as well. Possible flags are specified
916 * in @ref ucp_worker_address_flags_t. @note This is an input attribute.
917 */
918 uint32_t address_flags;
919
920 /**
921 * Worker address, which can be passed to remote instances of the UCP library
922 * in order to connect to this worker. The memory for the address handle is
923 * allocated by @ref ucp_worker_query "ucp_worker_query()" routine, and
924 * must be released by using @ref ucp_worker_release_address
925 * "ucp_worker_release_address()" routine.
926 */
927 ucp_address_t *address;
928
929 /**
930 * Size of worker address in bytes.
931 */
932 size_t address_length;
933 } ucp_worker_attr_t;
934
935
936 /**
937 * @ingroup UCP_WORKER
938 * @brief Tuning parameters for the UCP worker.
939 *
940 * The structure defines the parameters that are used for the
941 * UCP worker tuning during the UCP worker @ref ucp_worker_create "creation".
942 */
943 typedef struct ucp_worker_params {
944 /**
945 * Mask of valid fields in this structure, using bits from @ref ucp_worker_params_field.
946 * Fields not specified in this mask will be ignored.
947 * Provides ABI compatibility with respect to adding new fields.
948 */
949 uint64_t field_mask;
950
951 /**
952 * The parameter thread_mode suggests the thread safety mode which worker
953 * and the associated resources should be created with. This is an
954 * optional parameter. The default value is UCS_THREAD_MODE_SINGLE and
955 * it is used when the value of the parameter is not set. When this
956 * parameter along with its corresponding bit in the
957 * field_mask - UCP_WORKER_PARAM_FIELD_THREAD_MODE is set, the
958 * @ref ucp_worker_create attempts to create worker with this thread mode.
959 * The thread mode with which worker is created can differ from the
960 * suggested mode. The actual thread mode of the worker should be obtained
961 * using the query interface @ref ucp_worker_query.
962 */
963 ucs_thread_mode_t thread_mode;
964
965 /**
966 * Mask of which CPUs worker resources should preferably be allocated on.
967 * This value is optional.
968 * If it's not set (along with its corresponding bit in the field_mask -
969 * UCP_WORKER_PARAM_FIELD_CPU_MASK), resources are allocated according to
970 * system's default policy.
971 */
972 ucs_cpu_set_t cpu_mask;
973
974 /**
975 * Mask of events (@ref ucp_wakeup_event_t) which are expected on wakeup.
976 * This value is optional.
977 * If it's not set (along with its corresponding bit in the field_mask -
978 * UCP_WORKER_PARAM_FIELD_EVENTS), all types of events will trigger on
979 * wakeup.
980 */
981 unsigned events;
982
983 /**
984 * User data associated with the current worker.
985 * This value is optional.
986 * If it's not set (along with its corresponding bit in the field_mask -
987 * UCP_WORKER_PARAM_FIELD_USER_DATA), it will default to NULL.
988 */
989 void *user_data;
990
991 /**
992 * External event file descriptor.
993 * This value is optional.
994 * If @ref UCP_WORKER_PARAM_FIELD_EVENT_FD is set in the field_mask, events
995 * on the worker will be reported on the provided event file descriptor. In
996 * this case, calling @ref ucp_worker_get_efd will result in an error.
997 * The provided file descriptor must be capable of aggregating notifications
998 * for arbitrary events, for example @c epoll(7) on Linux systems.
999 * @ref user_data will be used as the event user-data on systems which
1000 * support it. For example, on Linux, it will be placed in
1001 * @c epoll_data_t::ptr, when returned from @c epoll_wait(2).
1002 *
1003 * Otherwise, events will be reported to the event file descriptor returned
1004 * from @ref ucp_worker_get_efd().
1005 */
1006 int event_fd;
1007
1008 } ucp_worker_params_t;
1009
1010
1011 /**
1012 * @ingroup UCP_WORKER
1013 * @brief UCP listener attributes.
1014 *
1015 * The structure defines the attributes which characterize
1016 * the particular listener.
1017 */
1018 typedef struct ucp_listener_attr {
1019 /**
1020 * Mask of valid fields in this structure, using bits from
1021 * @ref ucp_listener_attr_field.
1022 * Fields not specified in this mask will be ignored.
1023 * Provides ABI compatibility with respect to adding new fields.
1024 */
1025 uint64_t field_mask;
1026
1027 /**
1028 * Sockaddr on which this listener is listening for incoming connection
1029 * requests.
1030 */
1031 struct sockaddr_storage sockaddr;
1032 } ucp_listener_attr_t;
1033
1034
1035 /**
1036 * @ingroup UCP_WORKER
1037 * @brief UCP listener's connection request attributes.
1038 *
1039 * The structure defines the attributes that characterize
1040 * the particular connection request received on the server side.
1041 */
1042 typedef struct ucp_conn_request_attr {
1043 /**
1044 * Mask of valid fields in this structure, using bits from
1045 * @ref ucp_conn_request_attr_field.
1046 * Fields not specified in this mask will be ignored.
1047 * Provides ABI compatibility with respect to adding new fields.
1048 */
1049 uint64_t field_mask;
1050
1051 /**
1052 * The address of the remote client that sent the connection request to the
1053 * server.
1054 */
1055 struct sockaddr_storage client_address;
1056 } ucp_conn_request_attr_t;
1057
1058
1059 /**
1060 * @ingroup UCP_WORKER
1061 * @brief Parameters for a UCP listener object.
1062 *
1063 * This structure defines parameters for @ref ucp_listener_create, which is used to
1064 * listen for incoming client/server connections.
1065 */
1066 typedef struct ucp_listener_params {
1067 /**
1068 * Mask of valid fields in this structure, using bits from
1069 * @ref ucp_listener_params_field.
1070 * Fields not specified in this mask will be ignored.
1071 * Provides ABI compatibility with respect to adding new fields.
1072 */
1073 uint64_t field_mask;
1074
1075 /**
1076 * An address in the form of a sockaddr.
1077 * This field is mandatory for filling (along with its corresponding bit
1078 * in the field_mask - @ref UCP_LISTENER_PARAM_FIELD_SOCK_ADDR).
1079 * The @ref ucp_listener_create routine will return with an error if sockaddr
1080 * is not specified.
1081 */
1082 ucs_sock_addr_t sockaddr;
1083
1084 /**
1085 * Handler to endpoint creation in a client-server connection flow.
1086 * In order for the callback inside this handler to be invoked, the
1087 * UCP_LISTENER_PARAM_FIELD_ACCEPT_HANDLER needs to be set in the
1088 * field_mask.
1089 */
1090 ucp_listener_accept_handler_t accept_handler;
1091
1092 /**
1093 * Handler of an incoming connection request in a client-server connection
1094 * flow. In order for the callback inside this handler to be invoked, the
1095 * @ref UCP_LISTENER_PARAM_FIELD_CONN_HANDLER needs to be set in the
1096 * field_mask.
1097 */
1098 ucp_listener_conn_handler_t conn_handler;
1099 } ucp_listener_params_t;
1100
1101
1102 /**
1103 * @ingroup UCP_ENDPOINT
1104 * @brief Output parameter of @ref ucp_stream_worker_poll function.
1105 *
1106 * The structure defines the endpoint and its user data.
1107 */
1108 typedef struct ucp_stream_poll_ep {
1109 /**
1110 * Endpoint handle.
1111 */
1112 ucp_ep_h ep;
1113
1114 /**
1115 * User data associated with an endpoint passed in
1116 * @ref ucp_ep_params_t::user_data.
1117 */
1118 void *user_data;
1119
1120 /**
1121 * Reserved for future use.
1122 */
1123 unsigned flags;
1124
1125 /**
1126 * Reserved for future use.
1127 */
1128 uint8_t reserved[16];
1129 } ucp_stream_poll_ep_t;
1130
1131
1132 /**
1133 * @ingroup UCP_MEM
1134 * @brief Tuning parameters for the UCP memory mapping.
1135 *
1136 * The structure defines the parameters that are used for the
1137 * UCP memory mapping tuning during the @ref ucp_mem_map "ucp_mem_map" routine.
1138 */
1139 typedef struct ucp_mem_map_params {
1140 /**
1141 * Mask of valid fields in this structure, using bits from
1142 * @ref ucp_mem_map_params_field.
1143 * Fields not specified in this mask will be ignored.
1144 * Provides ABI compatibility with respect to adding new fields.
1145 */
1146 uint64_t field_mask;
1147
1148 /**
1149 * If the address is not NULL, the routine maps (registers) the memory segment
1150 * pointed to by this address.
1151 * If the pointer is NULL, the library allocates mapped (registered) memory
1152 * segment and returns its address in this argument.
1153 * Therefore, this value is optional.
1154 * If it's not set (along with its corresponding bit in the field_mask -
1155 * @ref UCP_MEM_MAP_PARAM_FIELD_ADDRESS), the ucp_mem_map routine will consider
1156 * address as set to NULL and will allocate memory.
1157 */
1158 void *address;
1159
1160 /**
1161 * Length (in bytes) to allocate or map (register).
1162 * This field is mandatory for filling (along with its corresponding bit
1163 * in the field_mask - @ref UCP_MEM_MAP_PARAM_FIELD_LENGTH).
1164 * The @ref ucp_mem_map routine will return with an error if the length isn't
1165 * specified.
1166 */
1167 size_t length;
1168
1169 /**
1170 * Allocation flags, e.g. @ref UCP_MEM_MAP_NONBLOCK.
1171 * This value is optional.
1172 * If it's not set (along with its corresponding bit in the field_mask -
1173 * @ref UCP_MEM_MAP_PARAM_FIELD_FLAGS), the @ref ucp_mem_map routine will
1174 * consider the flags as set to zero.
1175 */
1176 unsigned flags;
1177 } ucp_mem_map_params_t;
1178
1179
1180 /**
1181 * @ingroup UCP_CONTEXT
1182 * @brief UCP receive information descriptor
1183 *
1184 * The UCP receive information descriptor is allocated by application and filled
1185 * in with the information about the received message by @ref ucp_tag_probe_nb
1186 * or @ref ucp_tag_recv_request_test routines or
1187 * @ref ucp_tag_recv_callback_t callback argument.
1188 */
1189 struct ucp_tag_recv_info {
1190 /** Sender tag */
1191 ucp_tag_t sender_tag;
1192 /** The size of the received data */
1193 size_t length;
1194 };
1195
1196
1197 /**
1198 * @ingroup UCP_CONTEXT
1199 * @brief Operation parameters passed to @ref ucp_tag_send_nbx,
1200 * @ref ucp_tag_send_sync_nbx, @ref ucp_tag_recv_nbx, @ref ucp_put_nbx,
1201 * @ref ucp_get_nbx
1202 *
1203 * The structure @ref ucp_request_param_t is used to specify datatype of
1204 * operation, provide user request in case the external request is used,
1205 * set completion callback and custom user data passed to this callback.
1206 *
1207 * Example: implementation of function to send contiguous buffer to ep and
1208 * invoke callback function at operation completion. If the
1209 * operation completed immediately (status == UCS_OK) then
1210 * callback is not called.
1211 *
1212 * @code{.c}
1213 * ucs_status_ptr_t send_data(ucp_ep_h ep, void *buffer, size_t length,
1214 * ucp_tag_t tag, void *request)
1215 * {
1216 * ucp_request_param_t param = {
1217 * .op_attr_mask = UCP_OP_ATTR_FIELD_CALLBACK |
1218 * UCP_OP_ATTR_FIELD_REQUEST,
1219 * .request = request,
1220 * .cb.ucp_send_nbx_callback_t = custom_send_callback_f,
1221 * .user_data = pointer_to_user_context_passed_to_cb
1222 * };
1223 *
1224 * ucs_status_ptr_t status;
1225 *
1226 * status = ucp_tag_send_nbx(ep, buffer, length, tag, ¶m);
1227 * if (UCS_PTR_IS_ERR(status)) {
1228 * handle_error(status);
1229 * } else if (status == UCS_OK) {
1230 * // operation is completed
1231 * }
1232 *
1233 * return status;
1234 * }
1235 * @endcode
1236 */
1237 typedef struct {
1238 /**
1239 * Mask of valid fields in this structure and operation flags, using
1240 * bits from @ref ucp_op_attr_t. Fields not specified in this mask will be
1241 * ignored. Provides ABI compatibility with respect to adding new fields.
1242 */
1243 uint32_t op_attr_mask;
1244
1245 /* Operation specific flags. */
1246 uint32_t flags;
1247
1248 /**
1249 * Request handle allocated by the user. There should
1250 * be at least UCP request size bytes of available
1251 * space before the @a request. The size of the UCP request
1252 * can be obtained by @ref ucp_context_query function.
1253 */
1254 void *request;
1255
1256 /**
1257 * Callback function that is invoked whenever the
1258 * send or receive operation is completed.
1259 */
1260 union {
1261 ucp_send_nbx_callback_t send;
1262 ucp_tag_recv_nbx_callback_t recv;
1263 ucp_stream_recv_nbx_callback_t recv_stream;
1264 } cb;
1265
1266 /**
1267 * Datatype descriptor for the elements in the buffer. In case the
1268 * op_attr_mask & UCP_OP_ATTR_FIELD_DATATYPE bit is not set, then use
1269 * default datatype ucp_dt_make_contig(1)
1270 */
1271 ucp_datatype_t datatype;
1272
1273 /**
1274 * Pointer to user data passed to callback function.
1275 */
1276 void *user_data;
1277
1278 /**
1279 * Reply buffer. Can be used for storing operation result, for example by
1280 * @ref ucp_atomic_op_nbx.
1281 */
1282 void *reply_buffer;
1283 } ucp_request_param_t;
1284
1285
1286 /**
1287 * @ingroup UCP_CONFIG
1288 * @brief Read UCP configuration descriptor
1289 *
1290 * The routine fetches the information about UCP library configuration from
1291 * the run-time environment. Then, the fetched descriptor is used for
1292 * UCP library @ref ucp_init "initialization". The Application can print out the
1293 * descriptor using @ref ucp_config_print "print" routine. In addition
1294 * the application is responsible for @ref ucp_config_release "releasing" the
1295 * descriptor back to the UCP library.
1296 *
1297 * @param [in] env_prefix If non-NULL, the routine searches for the
1298 * environment variables that start with
1299 * @e \<env_prefix\>_UCX_ prefix.
1300 * Otherwise, the routine searches for the
1301 * environment variables that start with
1302 * @e UCX_ prefix.
1303 * @param [in] filename If non-NULL, read configuration from the file
1304 * defined by @e filename. If the file does not
1305 * exist, it will be ignored and no error reported
1306 * to the application.
1307 * @param [out] config_p Pointer to configuration descriptor as defined by
1308 * @ref ucp_config_t "ucp_config_t".
1309 *
1310 * @return Error code as defined by @ref ucs_status_t
1311 */
1312 ucs_status_t ucp_config_read(const char *env_prefix, const char *filename,
1313 ucp_config_t **config_p);
1314
1315
1316 /**
1317 * @ingroup UCP_CONFIG
1318 * @brief Release configuration descriptor
1319 *
1320 * The routine releases the configuration descriptor that was allocated through
1321 * @ref ucp_config_read "ucp_config_read()" routine.
1322 *
1323 * @param [out] config Configuration descriptor as defined by
1324 * @ref ucp_config_t "ucp_config_t".
1325 */
1326 void ucp_config_release(ucp_config_t *config);
1327
1328
1329 /**
1330 * @ingroup UCP_CONFIG
1331 * @brief Modify context configuration.
1332 *
1333 * The routine changes one configuration setting stored in @ref ucp_config_t
1334 * "configuration" descriptor.
1335 *
1336 * @param [in] config Configuration to modify.
1337 * @param [in] name Configuration variable name.
1338 * @param [in] value Value to set.
1339 *
1340 * @return Error code.
1341 */
1342 ucs_status_t ucp_config_modify(ucp_config_t *config, const char *name,
1343 const char *value);
1344
1345
1346 /**
1347 * @ingroup UCP_CONFIG
1348 * @brief Print configuration information
1349 *
1350 * The routine prints the configuration information that is stored in
1351 * @ref ucp_config_t "configuration" descriptor.
1352 *
1353 * @todo Expose ucs_config_print_flags_t
1354 *
1355 * @param [in] config @ref ucp_config_t "Configuration descriptor"
1356 * to print.
1357 * @param [in] stream Output stream to print the configuration to.
1358 * @param [in] title Configuration title to print.
1359 * @param [in] print_flags Flags that control various printing options.
1360 */
1361 void ucp_config_print(const ucp_config_t *config, FILE *stream,
1362 const char *title, ucs_config_print_flags_t print_flags);
1363
1364
1365 /**
1366 * @ingroup UCP_CONTEXT
1367 * @brief Get UCP library version.
1368 *
1369 * This routine returns the UCP library version.
1370 *
1371 * @param [out] major_version Filled with library major version.
1372 * @param [out] minor_version Filled with library minor version.
1373 * @param [out] release_number Filled with library release number.
1374 */
1375 void ucp_get_version(unsigned *major_version, unsigned *minor_version,
1376 unsigned *release_number);
1377
1378
1379 /**
1380 * @ingroup UCP_CONTEXT
1381 * @brief Get UCP library version as a string.
1382 *
1383 * This routine returns the UCP library version as a string which consists of:
1384 * "major.minor.release".
1385 */
1386 const char *ucp_get_version_string(void);
1387
1388
1389 /** @cond PRIVATE_INTERFACE */
1390 /**
1391 * @ingroup UCP_CONTEXT
1392 * @brief UCP context initialization with particular API version.
1393 *
1394 * This is an internal routine used to check compatibility with a particular
1395 * API version. @ref ucp_init should be used to create UCP context.
1396 */
1397 ucs_status_t ucp_init_version(unsigned api_major_version, unsigned api_minor_version,
1398 const ucp_params_t *params, const ucp_config_t *config,
1399 ucp_context_h *context_p);
1400 /** @endcond */
1401
1402
1403 /**
1404 * @ingroup UCP_CONTEXT
1405 * @brief UCP context initialization.
1406 *
1407 * This routine creates and initializes a @ref ucp_context_h
1408 * "UCP application context".
1409 *
1410 * @warning This routine must be called before any other UCP function
1411 * call in the application.
1412 *
1413 * This routine checks API version compatibility, then discovers the available
1414 * network interfaces, and initializes the network resources required for
1415 * discovering of the network and memory related devices.
1416 * This routine is responsible for initialization all information required for
1417 * a particular application scope, for example, MPI application, OpenSHMEM
1418 * application, etc.
1419 *
1420 * @note
1421 * @li Higher level protocols can add additional communication isolation, as
1422 * MPI does with it's communicator object. A single communication context may
1423 * be used to support multiple MPI communicators.
1424 * @li The context can be used to isolate the communication that corresponds to
1425 * different protocols. For example, if MPI and OpenSHMEM are using UCP to
1426 * isolate the MPI communication from the OpenSHMEM communication, users should
1427 * use different application context for each of the communication libraries.
1428 *
1429 * @param [in] config UCP configuration descriptor allocated through
1430 * @ref ucp_config_read "ucp_config_read()" routine.
1431 * @param [in] params User defined @ref ucp_params_t configurations for the
1432 * @ref ucp_context_h "UCP application context".
1433 * @param [out] context_p Initialized @ref ucp_context_h
1434 * "UCP application context".
1435 *
1436 * @return Error code as defined by @ref ucs_status_t
1437 */
ucp_init(const ucp_params_t * params,const ucp_config_t * config,ucp_context_h * context_p)1438 static inline ucs_status_t ucp_init(const ucp_params_t *params,
1439 const ucp_config_t *config,
1440 ucp_context_h *context_p)
1441 {
1442 return ucp_init_version(UCP_API_MAJOR, UCP_API_MINOR, params, config,
1443 context_p);
1444 }
1445
1446
1447 /**
1448 * @ingroup UCP_CONTEXT
1449 * @brief Release UCP application context.
1450 *
1451 * This routine finalizes and releases the resources associated with a
1452 * @ref ucp_context_h "UCP application context".
1453 *
1454 * @warning An application cannot call any UCP routine
1455 * once the UCP application context released.
1456 *
1457 * The cleanup process releases and shuts down all resources associated with
1458 * the application context. After calling this routine, calling any UCP
1459 * routine without calling @ref ucp_init "UCP initialization routine" is invalid.
1460 *
1461 * @param [in] context_p Handle to @ref ucp_context_h
1462 * "UCP application context".
1463 */
1464 void ucp_cleanup(ucp_context_h context_p);
1465
1466
1467 /**
1468 * @ingroup UCP_CONTEXT
1469 * @brief Get attributes specific to a particular context.
1470 *
1471 * This routine fetches information about the context.
1472 *
1473 * @param [in] context_p Handle to @ref ucp_context_h
1474 * "UCP application context".
1475 *
1476 * @param [out] attr Filled with attributes of @p context_p context.
1477 *
1478 * @return Error code as defined by @ref ucs_status_t
1479 */
1480 ucs_status_t ucp_context_query(ucp_context_h context_p,
1481 ucp_context_attr_t *attr);
1482
1483
1484 /**
1485 * @ingroup UCP_CONTEXT
1486 * @brief Print context information.
1487 *
1488 * This routine prints information about the context configuration: including
1489 * memory domains, transport resources, and other useful information associated
1490 * with the context.
1491 *
1492 * @param [in] context Print this context object's configuration.
1493 * @param [in] stream Output stream on which to print the information.
1494 */
1495 void ucp_context_print_info(const ucp_context_h context, FILE *stream);
1496
1497
1498 /**
1499 * @ingroup UCP_WORKER
1500 * @brief Create a worker object.
1501 *
1502 * This routine allocates and initializes a @ref ucp_worker_h "worker" object.
1503 * Each worker is associated with one and only one @ref ucp_context_h
1504 * "application" context. In the same time, an application context can create
1505 * multiple @ref ucp_worker_h "workers" in order to enable concurrent access to
1506 * communication resources. For example, application can allocate a dedicated
1507 * worker for each application thread, where every worker can be progressed
1508 * independently of others.
1509 *
1510 * @note The worker object is allocated within context of the calling thread
1511 *
1512 * @param [in] context Handle to @ref ucp_context_h
1513 * "UCP application context".
1514 * @param [in] params User defined @ref ucp_worker_params_t configurations for the
1515 * @ref ucp_worker_h "UCP worker".
1516 * @param [out] worker_p A pointer to the worker object allocated by the
1517 * UCP library
1518 *
1519 * @return Error code as defined by @ref ucs_status_t
1520 */
1521 ucs_status_t ucp_worker_create(ucp_context_h context,
1522 const ucp_worker_params_t *params,
1523 ucp_worker_h *worker_p);
1524
1525
1526 /**
1527 * @ingroup UCP_WORKER
1528 * @brief Destroy a worker object.
1529 *
1530 * This routine releases the resources associated with a
1531 * @ref ucp_worker_h "UCP worker".
1532 *
1533 * @warning Once the UCP worker destroy the worker handle cannot be used with any
1534 * UCP routine.
1535 *
1536 * The destroy process releases and shuts down all resources associated with
1537 * the @ref ucp_worker_h "worker".
1538 *
1539 * @param [in] worker Worker object to destroy.
1540 */
1541 void ucp_worker_destroy(ucp_worker_h worker);
1542
1543
1544 /**
1545 * @ingroup UCP_WORKER
1546 * @brief Get attributes specific to a particular worker.
1547 *
1548 * This routine fetches information about the worker.
1549 *
1550 * @param [in] worker Worker object to query.
1551 * @param [out] attr Filled with attributes of worker.
1552 *
1553 * @return Error code as defined by @ref ucs_status_t
1554 */
1555 ucs_status_t ucp_worker_query(ucp_worker_h worker,
1556 ucp_worker_attr_t *attr);
1557
1558
1559 /**
1560 * @ingroup UCP_WORKER
1561 * @brief Print information about the worker.
1562 *
1563 * This routine prints information about the protocols being used, thresholds,
1564 * UCT transport methods, and other useful information associated with the worker.
1565 *
1566 * @param [in] worker Worker object to print information for.
1567 * @param [in] stream Output stream to print the information to.
1568 */
1569 void ucp_worker_print_info(ucp_worker_h worker, FILE *stream);
1570
1571
1572 /**
1573 * @ingroup UCP_WORKER
1574 * @brief Get the address of the worker object.
1575 *
1576 * This routine returns the address of the worker object. This address can be
1577 * passed to remote instances of the UCP library in order to connect to this
1578 * worker. The memory for the address handle is allocated by this function, and
1579 * must be released by using @ref ucp_worker_release_address
1580 * "ucp_worker_release_address()" routine.
1581 *
1582 * @param [in] worker Worker object whose address to return.
1583 * @param [out] address_p A pointer to the worker address.
1584 * @param [out] address_length_p The size in bytes of the address.
1585 *
1586 * @return Error code as defined by @ref ucs_status_t
1587 */
1588 ucs_status_t ucp_worker_get_address(ucp_worker_h worker,
1589 ucp_address_t **address_p,
1590 size_t *address_length_p);
1591
1592
1593 /**
1594 * @ingroup UCP_WORKER
1595 * @brief Release an address of the worker object.
1596 *
1597 * This routine release an @ref ucp_address_t "address handle" associated within
1598 * the @ref ucp_worker_h "worker" object.
1599 *
1600 * @warning Once the address released the address handle cannot be used with any
1601 * UCP routine.
1602 *
1603 * @param [in] worker Worker object that is associated with the
1604 * address object.
1605 * @param [in] address Address to release; the address object has to
1606 * be allocated using @ref ucp_worker_get_address
1607 * "ucp_worker_get_address()" routine.
1608 *
1609 * @todo We should consider to change it to return int so we can catch the
1610 * errors when worker != address
1611 */
1612 void ucp_worker_release_address(ucp_worker_h worker, ucp_address_t *address);
1613
1614
1615 /**
1616 * @ingroup UCP_WORKER
1617 * @brief Progress all communications on a specific worker.
1618 *
1619 * This routine explicitly progresses all communication operations on a worker.
1620 *
1621 * @note
1622 * @li Typically, request wait and test routines call @ref
1623 * ucp_worker_progress "this routine" to progress any outstanding operations.
1624 * @li Transport layers, implementing asynchronous progress using threads,
1625 * require callbacks and other user code to be thread safe.
1626 * @li The state of communication can be advanced (progressed) by blocking
1627 * routines. Nevertheless, the non-blocking routines can not be used for
1628 * communication progress.
1629 *
1630 * @param [in] worker Worker to progress.
1631 *
1632 * @return Non-zero if any communication was progressed, zero otherwise.
1633 */
1634 unsigned ucp_worker_progress(ucp_worker_h worker);
1635
1636
1637 /**
1638 * @ingroup UCP_WORKER
1639 * @brief Poll for endpoints that are ready to consume streaming data.
1640 *
1641 * This non-blocking routine returns endpoints on a worker which are ready
1642 * to consume streaming data. The ready endpoints are placed in @a poll_eps
1643 * array, and the function return value indicates how many are there.
1644 *
1645 * @param [in] worker Worker to poll.
1646 * @param [out] poll_eps Pointer to array of endpoints, should be
1647 * allocated by user.
1648 * @param [in] max_eps Maximal number of endpoints which should be filled
1649 * in @a poll_eps.
1650 * @param [in] flags Reserved for future use.
1651 *
1652 * @return Negative value indicates an error according to @ref ucs_status_t.
1653 * On success, non-negative value (less or equal @a max_eps) indicates
1654 * actual number of endpoints filled in @a poll_eps array.
1655 *
1656 */
1657 ssize_t ucp_stream_worker_poll(ucp_worker_h worker,
1658 ucp_stream_poll_ep_t *poll_eps, size_t max_eps,
1659 unsigned flags);
1660
1661
1662 /**
1663 * @ingroup UCP_WAKEUP
1664 * @brief Obtain an event file descriptor for event notification.
1665 *
1666 * This routine returns a valid file descriptor for polling functions.
1667 * The file descriptor will get signaled when an event occurs, as part of the
1668 * wake-up mechanism. Signaling means a call to poll() or select() with this
1669 * file descriptor will return at this point, with this descriptor marked as the
1670 * reason (or one of the reasons) the function has returned. The user does not
1671 * need to release the obtained file descriptor.
1672 *
1673 * The wake-up mechanism exists to allow for the user process to register for
1674 * notifications on events of the underlying interfaces, and wait until such
1675 * occur. This is an alternative to repeated polling for request completion.
1676 * The goal is to allow for waiting while consuming minimal resources from the
1677 * system. This is recommended for cases where traffic is infrequent, and
1678 * latency can be traded for lower resource consumption while waiting for it.
1679 *
1680 * There are two alternative ways to use the wakeup mechanism: the first is the
1681 * file descriptor obtained per worker (this function) and the second is the
1682 * @ref ucp_worker_wait function for waiting on the next event internally.
1683 *
1684 * @note UCP @ref ucp_feature "features" have to be triggered
1685 * with @ref UCP_FEATURE_WAKEUP to select proper transport
1686 *
1687 * @param [in] worker Worker of notified events.
1688 * @param [out] fd File descriptor.
1689 *
1690 * @return Error code as defined by @ref ucs_status_t
1691 */
1692 ucs_status_t ucp_worker_get_efd(ucp_worker_h worker, int *fd);
1693
1694
1695 /**
1696 * @ingroup UCP_WAKEUP
1697 * @brief Wait for an event of the worker.
1698 *
1699 * This routine waits (blocking) until an event has happened, as part of the
1700 * wake-up mechanism.
1701 *
1702 * This function is guaranteed to return only if new communication events occur
1703 * on the @a worker. Therefore one must drain all existing events before waiting
1704 * on the file descriptor. This can be achieved by calling
1705 * @ref ucp_worker_progress repeatedly until it returns 0.
1706 *
1707 * There are two alternative ways to use the wakeup mechanism. The first is by
1708 * polling on a per-worker file descriptor obtained from @ref ucp_worker_get_efd.
1709 * The second is by using this function to perform an internal wait for the next
1710 * event associated with the specified worker.
1711 *
1712 * @note During the blocking call the wake-up mechanism relies on other means of
1713 * notification and may not progress some of the requests as it would when
1714 * calling @ref ucp_worker_progress (which is not invoked in that duration).
1715 *
1716 * @note UCP @ref ucp_feature "features" have to be triggered
1717 * with @ref UCP_FEATURE_WAKEUP to select proper transport
1718 *
1719 * @param [in] worker Worker to wait for events on.
1720 *
1721 * @return Error code as defined by @ref ucs_status_t
1722 */
1723 ucs_status_t ucp_worker_wait(ucp_worker_h worker);
1724
1725
1726 /**
1727 * @ingroup UCP_WAKEUP
1728 * @brief Wait for memory update on the address
1729 *
1730 * This routine waits for a memory update at the local memory @a address. This
1731 * is a blocking routine. The routine returns when the memory address is
1732 * updated ("write") or an event occurs in the system.
1733 *
1734 * This function is guaranteed to return only if new communication events occur
1735 * on the worker or @a address is modified. Therefore one must drain all existing
1736 * events before waiting on the file descriptor. This can be achieved by calling
1737 * @ref ucp_worker_progress repeatedly until it returns 0.
1738 *
1739 * @note This routine can be used by an application that executes busy-waiting
1740 * loop checking for a memory update. Instead of continuous busy-waiting on an
1741 * address the application can use @a ucp_worker_wait_mem, which may suspend
1742 * execution until the memory is updated. The goal of the routine is to provide
1743 * an opportunity for energy savings for architectures that support this
1744 * functionality.
1745 *
1746 * @param [in] worker Worker to wait for updates on.
1747 * @param [in] address Local memory address
1748 */
1749 void ucp_worker_wait_mem(ucp_worker_h worker, void *address);
1750
1751
1752 /**
1753 * @ingroup UCP_WAKEUP
1754 * @brief Turn on event notification for the next event.
1755 *
1756 * This routine needs to be called before waiting on each notification on this
1757 * worker, so will typically be called once the processing of the previous event
1758 * is over, as part of the wake-up mechanism.
1759 *
1760 * The worker must be armed before waiting on an event (must be re-armed after
1761 * it has been signaled for re-use) with @ref ucp_worker_arm.
1762 * The events triggering a signal of the file descriptor from
1763 * @ref ucp_worker_get_efd depend on the interfaces used by the worker and
1764 * defined in the transport layer, and typically represent a request completion
1765 * or newly available resources. It can also be triggered by calling
1766 * @ref ucp_worker_signal .
1767 *
1768 * The file descriptor is guaranteed to become signaled only if new communication
1769 * events occur on the @a worker. Therefore one must drain all existing events
1770 * before waiting on the file descriptor. This can be achieved by calling
1771 * @ref ucp_worker_progress repeatedly until it returns 0.
1772 *
1773 * @code {.c}
1774 * void application_initialization() {
1775 * // should be called once in application init flow and before
1776 * // process_comminucation() is used
1777 * ...
1778 * status = ucp_worker_get_efd(worker, &fd);
1779 * ...
1780 * }
1781 *
1782 * void process_comminucation() {
1783 * // should be called every time need to wait for some condition such as
1784 * // ucp request completion in sleep mode.
1785 *
1786 * for (;;) {
1787 * // check for stop condition as long as progress is made
1788 * if (check_for_events()) {
1789 * break;
1790 * } else if (ucp_worker_progress(worker)) {
1791 * continue; // some progress happened but condition not met
1792 * }
1793 *
1794 * // arm the worker and clean-up fd
1795 * status = ucp_worker_arm(worker);
1796 * if (UCS_OK == status) {
1797 * poll(&fds, nfds, timeout); // wait for events (sleep mode)
1798 * } else if (UCS_ERR_BUSY == status) {
1799 * continue; // could not arm, need to progress more
1800 * } else {
1801 * abort();
1802 * }
1803 * }
1804 * }
1805 * @endcode
1806 *
1807 * @note UCP @ref ucp_feature "features" have to be triggered
1808 * with @ref UCP_FEATURE_WAKEUP to select proper transport
1809 *
1810 * @param [in] worker Worker of notified events.
1811 *
1812 * @return ::UCS_OK The operation completed successfully. File descriptor
1813 * will be signaled by new events.
1814 * @return ::UCS_ERR_BUSY There are unprocessed events which prevent the
1815 * file descriptor from being armed. These events should
1816 * be removed by calling @ref ucp_worker_progress().
1817 * The operation is not completed. File descriptor
1818 * will not be signaled by new events.
1819 * @return @ref ucs_status_t "Other" different error codes in case of issues.
1820 */
1821 ucs_status_t ucp_worker_arm(ucp_worker_h worker);
1822
1823
1824 /**
1825 * @ingroup UCP_WAKEUP
1826 * @brief Cause an event of the worker.
1827 *
1828 * This routine signals that the event has happened, as part of the wake-up
1829 * mechanism. This function causes a blocking call to @ref ucp_worker_wait or
1830 * waiting on a file descriptor from @ref ucp_worker_get_efd to return, even
1831 * if no event from the underlying interfaces has taken place.
1832 *
1833 * @note It's safe to use this routine from any thread, even if UCX is compiled
1834 * without multi-threading support and/or initialized with any value of
1835 * @ref ucp_params_t::mt_workers_shared and
1836 * @ref ucp_worker_params_t::thread_mode parameters
1837 *
1838 * @param [in] worker Worker to wait for events on.
1839 *
1840 * @return Error code as defined by @ref ucs_status_t
1841 */
1842 ucs_status_t ucp_worker_signal(ucp_worker_h worker);
1843
1844
1845 /**
1846 * @ingroup UCP_WORKER
1847 * @brief Accept connections on a local address of the worker object.
1848 *
1849 * This routine binds the worker object to a @ref ucs_sock_addr_t sockaddr
1850 * which is set by the user.
1851 * The worker will listen to incoming connection requests and upon receiving such
1852 * a request from the remote peer, an endpoint to it will be created.
1853 * The user's call-back will be invoked once the endpoint is created.
1854 *
1855 * @param [in] worker Worker object that is associated with the
1856 * params object.
1857 * @param [in] params User defined @ref ucp_listener_params_t
1858 * configurations for the @ref ucp_listener_h.
1859 * @param [out] listener_p A handle to the created listener, can be released
1860 * by calling @ref ucp_listener_destroy
1861 *
1862 * @return Error code as defined by @ref ucs_status_t
1863 */
1864 ucs_status_t ucp_listener_create(ucp_worker_h worker,
1865 const ucp_listener_params_t *params,
1866 ucp_listener_h *listener_p);
1867
1868
1869 /**
1870 * @ingroup UCP_WORKER
1871 * @brief Stop accepting connections on a local address of the worker object.
1872 *
1873 * This routine unbinds the worker from the given handle and stops
1874 * listening for incoming connection requests on it.
1875 *
1876 * @param [in] listener A handle to the listener to stop listening on.
1877 */
1878 void ucp_listener_destroy(ucp_listener_h listener);
1879
1880
1881 /**
1882 * @ingroup UCP_WORKER
1883 * @brief Get attributes specific to a particular listener.
1884 *
1885 * This routine fetches information about the listener.
1886 *
1887 * @param [in] listener listener object to query.
1888 * @param [out] attr Filled with attributes of the listener.
1889 *
1890 * @return Error code as defined by @ref ucs_status_t
1891 */
1892 ucs_status_t ucp_listener_query(ucp_listener_h listener, ucp_listener_attr_t *attr);
1893
1894
1895 /**
1896 * @ingroup UCP_WORKER
1897 * @brief Get attributes specific to a particular connection request received
1898 * on the server side.
1899 *
1900 * This routine fetches information about the connection request.
1901 *
1902 * @param [in] conn_request connection request object to query.
1903 * @param [out] attr Filled with attributes of the connection request.
1904 *
1905 * @return Error code as defined by @ref ucs_status_t
1906 */
1907 ucs_status_t ucp_conn_request_query(ucp_conn_request_h conn_request,
1908 ucp_conn_request_attr_t *attr);
1909
1910
1911 /**
1912 * @ingroup UCP_ENDPOINT
1913 * @brief Create and connect an endpoint.
1914 *
1915 * This routine creates and connects an @ref ucp_ep_h "endpoint" on a @ref
1916 * ucp_worker_h "local worker" for a destination @ref ucp_address_t "address"
1917 * that identifies the remote @ref ucp_worker_h "worker". This function is
1918 * non-blocking, and communications may begin immediately after it returns. If
1919 * the connection process is not completed, communications may be delayed.
1920 * The created @ref ucp_ep_h "endpoint" is associated with one and only one
1921 * @ref ucp_worker_h "worker".
1922 *
1923 * @param [in] worker Handle to the worker; the endpoint
1924 * is associated with the worker.
1925 * @param [in] params User defined @ref ucp_ep_params_t configurations
1926 * for the @ref ucp_ep_h "UCP endpoint".
1927 * @param [out] ep_p A handle to the created endpoint.
1928 *
1929 * @return Error code as defined by @ref ucs_status_t
1930 *
1931 * @note One of the following fields has to be specified:
1932 * - ucp_ep_params_t::address
1933 * - ucp_ep_params_t::sockaddr
1934 * - ucp_ep_params_t::conn_request
1935
1936 * @note By default, ucp_ep_create() will connect an endpoint to itself if
1937 * the endpoint is destined to the same @a worker on which it was created,
1938 * i.e. @a params.address belongs to @a worker. This behavior can be changed by
1939 * passing the @ref UCP_EP_PARAMS_FLAGS_NO_LOOPBACK flag in @a params.flags.
1940 * In that case, the endpoint will be connected to the *next* endpoint created
1941 * in the same way on the same @a worker.
1942 */
1943 ucs_status_t ucp_ep_create(ucp_worker_h worker, const ucp_ep_params_t *params,
1944 ucp_ep_h *ep_p);
1945
1946
1947 /**
1948 * @ingroup UCP_ENDPOINT
1949 *
1950 * @brief Non-blocking @ref ucp_ep_h "endpoint" closure.
1951 *
1952 * This routine releases the @ref ucp_ep_h "endpoint". The endpoint closure
1953 * process depends on the selected @a mode.
1954 *
1955 * @param [in] ep Handle to the endpoint to close.
1956 * @param [in] mode One from @ref ucp_ep_close_mode value.
1957 *
1958 * @return UCS_OK - The endpoint is closed successfully.
1959 * @return UCS_PTR_IS_ERR(_ptr) - The closure failed and an error code indicates
1960 * the transport level status. However, resources
1961 * are released and the @a endpoint can no longer
1962 * be used.
1963 * @return otherwise - The closure process is started, and can be
1964 * completed at any point in time. A request handle
1965 * is returned to the application in order to track
1966 * progress of the endpoint closure. The application
1967 * is responsible for releasing the handle using the
1968 * @ref ucp_request_free routine.
1969 *
1970 * @note @ref ucp_ep_close_nb replaces deprecated @ref ucp_disconnect_nb and
1971 * @ref ucp_ep_destroy
1972 */
1973 ucs_status_ptr_t ucp_ep_close_nb(ucp_ep_h ep, unsigned mode);
1974
1975
1976 /**
1977 * @ingroup UCP_ENDPOINT
1978 *
1979 * @brief Non-blocking @ref ucp_ep_h "endpoint" closure.
1980 *
1981 * @param [in] ep Handle to the endpoint to close.
1982 * @param [in] param Operation parameters, see @ref ucp_request_param_t.
1983 * This operation supports specific flags, which can be
1984 * passed in @a param by @ref ucp_request_param_t.flags.
1985 * The exact set of flags is defined
1986 * by @ref ucp_ep_close_flags_t.
1987 *
1988 * @return NULL - The endpoint is closed successfully.
1989 * @return UCS_PTR_IS_ERR(_ptr) - The closure failed and an error code indicates
1990 * the transport level status. However, resources
1991 * are released and the @a endpoint can no longer
1992 * be used.
1993 * @return otherwise - The closure process is started, and can be
1994 * completed at any point in time. A request
1995 * handle is returned to the application in order
1996 * to track progress of the endpoint closure.
1997 */
1998 ucs_status_ptr_t ucp_ep_close_nbx(ucp_ep_h ep,
1999 const ucp_request_param_t *param);
2000
2001
2002 /**
2003 * @ingroup UCP_WORKER
2004 *
2005 * @brief Reject an incoming connection request.
2006 *
2007 * Reject the incoming connection request and release associated resources. If
2008 * the remote initiator endpoint has set an @ref ucp_ep_params_t::err_handler,
2009 * it will be invoked with status @ref UCS_ERR_REJECTED.
2010 *
2011 * @param [in] listener Handle to the listener on which the connection
2012 * request was received.
2013 * @param [in] conn_request Handle to the connection request to reject.
2014 *
2015 * @return Error code as defined by @ref ucs_status_t
2016 *
2017 */
2018 ucs_status_t ucp_listener_reject(ucp_listener_h listener,
2019 ucp_conn_request_h conn_request);
2020
2021
2022 /**
2023 * @ingroup UCP_ENDPOINT
2024 * @brief Print endpoint information.
2025 *
2026 * This routine prints information about the endpoint transport methods, their
2027 * thresholds, and other useful information associated with the endpoint.
2028 *
2029 * @param [in] ep Endpoint object whose configuration to print.
2030 * @param [in] stream Output stream to print the information to.
2031 */
2032 void ucp_ep_print_info(ucp_ep_h ep, FILE *stream);
2033
2034
2035 /**
2036 * @ingroup UCP_ENDPOINT
2037 *
2038 * @brief Non-blocking flush of outstanding AMO and RMA operations on the
2039 * @ref ucp_ep_h "endpoint".
2040 *
2041 * This routine flushes all outstanding AMO and RMA communications on the
2042 * @ref ucp_ep_h "endpoint". All the AMO and RMA operations issued on the
2043 * @a ep prior to this call are completed both at the origin and at the target
2044 * @ref ucp_ep_h "endpoint" when this call returns.
2045 *
2046 * @param [in] ep UCP endpoint.
2047 * @param [in] flags Flags for flush operation. Reserved for future use.
2048 * @param [in] cb Callback which will be called when the flush operation
2049 * completes.
2050 *
2051 * @return NULL - The flush operation was completed immediately.
2052 * @return UCS_PTR_IS_ERR(_ptr) - The flush operation failed.
2053 * @return otherwise - Flush operation was scheduled and can be completed
2054 * in any point in time. The request handle is returned
2055 * to the application in order to track progress. The
2056 * application is responsible for releasing the handle
2057 * using @ref ucp_request_free "ucp_request_free()"
2058 * routine.
2059 *
2060 *
2061 * The following example demonstrates how blocking flush can be implemented
2062 * using non-blocking flush:
2063 * @code {.c}
2064 * void empty_function(void *request, ucs_status_t status)
2065 * {
2066 * }
2067 *
2068 * ucs_status_t blocking_ep_flush(ucp_ep_h ep, ucp_worker_h worker)
2069 * {
2070 * void *request;
2071 *
2072 * request = ucp_ep_flush_nb(ep, 0, empty_function);
2073 * if (request == NULL) {
2074 * return UCS_OK;
2075 * } else if (UCS_PTR_IS_ERR(request)) {
2076 * return UCS_PTR_STATUS(request);
2077 * } else {
2078 * ucs_status_t status;
2079 * do {
2080 * ucp_worker_progress(worker);
2081 * status = ucp_request_check_status(request);
2082 * } while (status == UCS_INPROGRESS);
2083 * ucp_request_free(request);
2084 * return status;
2085 * }
2086 * }
2087 * @endcode */
2088 ucs_status_ptr_t ucp_ep_flush_nb(ucp_ep_h ep, unsigned flags,
2089 ucp_send_callback_t cb);
2090
2091
2092 /**
2093 * @ingroup UCP_ENDPOINT
2094 *
2095 * @brief Non-blocking flush of outstanding AMO and RMA operations on the
2096 * @ref ucp_ep_h "endpoint".
2097 *
2098 * This routine flushes all outstanding AMO and RMA communications on the
2099 * @ref ucp_ep_h "endpoint". All the AMO and RMA operations issued on the
2100 * @a ep prior to this call are completed both at the origin and at the target
2101 * @ref ucp_ep_h "endpoint" when this call returns.
2102 *
2103 * @param [in] ep UCP endpoint.
2104 * @param [in] param Operation parameters, see @ref ucp_request_param_t.
2105 *
2106 * @return NULL - The flush operation was completed immediately.
2107 * @return UCS_PTR_IS_ERR(_ptr) - The flush operation failed.
2108 * @return otherwise - Flush operation was scheduled and can be
2109 * completed in any point in time. The request
2110 * handle is returned to the application in
2111 * order to track progress.
2112 */
2113 ucs_status_ptr_t ucp_ep_flush_nbx(ucp_ep_h ep, const ucp_request_param_t *param);
2114
2115
2116 /**
2117 * @ingroup UCP_MEM
2118 * @brief Map or allocate memory for zero-copy operations.
2119 *
2120 * This routine maps or/and allocates a user-specified memory segment with @ref
2121 * ucp_context_h "UCP application context" and the network resources associated
2122 * with it. If the application specifies NULL as an address for the memory
2123 * segment, the routine allocates a mapped memory segment and returns its
2124 * address in the @a address_p argument. The network stack associated with an
2125 * application context can typically send and receive data from the mapped
2126 * memory without CPU intervention; some devices and associated network stacks
2127 * require the memory to be mapped to send and receive data. The @ref ucp_mem_h
2128 * "memory handle" includes all information required to access the memory
2129 * locally using UCP routines, while @ref ucp_rkey_h
2130 * "remote registration handle" provides an information that is necessary for
2131 * remote memory access.
2132 *
2133 * @note
2134 * Another well know terminology for the "map" operation that is typically
2135 * used in the context of networking is memory "registration" or "pinning". The
2136 * UCP library registers the memory the available hardware so it can be
2137 * assessed directly by the hardware.
2138 *
2139 * Memory mapping assumptions:
2140 * @li A given memory segment can be mapped by several different communication
2141 * stacks, if these are compatible.
2142 * @li The @a memh_p handle returned may be used with any sub-region of the
2143 * mapped memory.
2144 * @li If a large segment is registered, and then segmented for subsequent use
2145 * by a user, then the user is responsible for segmentation and subsequent
2146 * management.
2147 *
2148 * <table>
2149 * <caption>Matrix of behavior</caption>
2150 * <tr><th>parameter/flag <td align="center">@ref UCP_MEM_MAP_NONBLOCK "NONBLOCK"</td>
2151 * <td align="center">@ref UCP_MEM_MAP_ALLOCATE "ALLOCATE"</td>
2152 * <td align="center">@ref UCP_MEM_MAP_FIXED "FIXED"</td>
2153 * <td align="center">@ref ucp_mem_map_params.address "address"</td>
2154 * <td align="center">@b result
2155 * <tr><td rowspan="8" align="center">@b value <td rowspan="8" align="center">0/1 - the value\n only affects the\n register/map\n phase</td>
2156 * <td align="center">0 <td align="center">0 <td align="center">0 <td align="center">@ref anch_err "error" if length > 0
2157 * <tr> <td align="center">1 <td align="center">0 <td align="center">0 <td align="center">@ref anch_alloc_reg "alloc+register"
2158 * <tr> <td align="center">0 <td align="center">1 <td align="center">0 <td align="center">@ref anch_err "error"</td>
2159 * <tr> <td align="center">0 <td align="center">0 <td align="center">defined <td align="center">@ref anch_reg "register"
2160 * <tr> <td align="center">1 <td align="center">1 <td align="center">0 <td align="center">@ref anch_err "error"</td>
2161 * <tr> <td align="center">1 <td align="center">0 <td align="center">defined <td align="center">@ref anch_alloc_hint_reg "alloc+register,hint"
2162 * <tr> <td align="center">0 <td align="center">1 <td align="center">defined <td align="center">@ref anch_err "error"</td>
2163 * <tr> <td align="center">1 <td align="center">1 <td align="center">defined <td align="center">@ref anch_alloc_fixed_reg "alloc+register,fixed"
2164 * </table>
2165 *
2166 * @note
2167 * @li \anchor anch_reg @b register means that the memory will be registered in
2168 * corresponding transports for RMA/AMO operations. This case intends that
2169 * the memory was allocated by user before.
2170 * @li \anchor anch_alloc_reg @b alloc+register means that the memory will be allocated
2171 * in the memory provided by the system and registered in corresponding
2172 * transports for RMA/AMO operations.
2173 * @li \anchor anch_alloc_hint_reg <b>alloc+register,hint</b> means that
2174 * the memory will be allocated with using @ref ucp_mem_map_params.address
2175 * as a hint and registered in corresponding transports for RMA/AMO operations.
2176 * @li \anchor anch_alloc_fixed_reg <b>alloc+register,fixed</b> means that the memory
2177 * will be allocated and registered in corresponding transports for RMA/AMO
2178 * operations.
2179 * @li \anchor anch_err @b error is an erroneous combination of the parameters.
2180 *
2181 * @param [in] context Application @ref ucp_context_h "context" to map
2182 * (register) and allocate the memory on.
2183 * @param [in] params User defined @ref ucp_mem_map_params_t configurations
2184 * for the @ref ucp_mem_h "UCP memory handle".
2185 * @param [out] memh_p UCP @ref ucp_mem_h "handle" for the allocated
2186 * segment.
2187 *
2188 * @return Error code as defined by @ref ucs_status_t
2189 */
2190 ucs_status_t ucp_mem_map(ucp_context_h context, const ucp_mem_map_params_t *params,
2191 ucp_mem_h *memh_p);
2192
2193
2194 /**
2195 * @ingroup UCP_MEM
2196 * @brief Unmap memory segment
2197 *
2198 * This routine unmaps a user specified memory segment, that was previously
2199 * mapped using the @ref ucp_mem_map "ucp_mem_map()" routine. The unmap
2200 * routine will also release the resources associated with the memory
2201 * @ref ucp_mem_h "handle". When the function returns, the @ref ucp_mem_h
2202 * and associated @ref ucp_rkey_h "remote key" will be invalid and cannot be
2203 * used with any UCP routine.
2204 *
2205 * @note
2206 * Another well know terminology for the "unmap" operation that is typically
2207 * used in the context of networking is memory "de-registration". The UCP
2208 * library de-registers the memory the available hardware so it can be returned
2209 * back to the operation system.
2210 *
2211 * Error cases:
2212 * @li Once memory is unmapped a network access to the region may cause a
2213 * failure.
2214 *
2215 * @param [in] context Application @ref ucp_context_h "context" which was
2216 * used to allocate/map the memory.
2217 * @param [in] memh @ref ucp_mem_h "Handle" to memory region.
2218 *
2219 * @return Error code as defined by @ref ucs_status_t
2220 */
2221 ucs_status_t ucp_mem_unmap(ucp_context_h context, ucp_mem_h memh);
2222
2223
2224 /**
2225 * @ingroup UCP_MEM
2226 * @brief query mapped memory segment
2227 *
2228 * This routine returns address and length of memory segment mapped with
2229 * @ref ucp_mem_map "ucp_mem_map()" routine.
2230 *
2231 * @param [in] memh @ref ucp_mem_h "Handle" to memory region.
2232 * @param [out] attr Filled with attributes of the @ref ucp_mem_h
2233 * "UCP memory handle".
2234 *
2235 * @return Error code as defined by @ref ucs_status_t
2236 */
2237 ucs_status_t ucp_mem_query(const ucp_mem_h memh, ucp_mem_attr_t *attr);
2238
2239
2240 /**
2241 * @ingroup UCP_MEM
2242 * @brief Print memory mapping information.
2243 *
2244 * This routine maps memory and prints information about the created memory handle:
2245 * including the mapped memory length, the allocation method, and other useful
2246 * information associated with the memory handle.
2247 *
2248 * @param [in] mem_size Size of the memory to map.
2249 * @param [in] context The context on which the memory is mapped.
2250 * @param [in] stream Output stream on which to print the information.
2251 */
2252 void ucp_mem_print_info(const char *mem_size, ucp_context_h context, FILE *stream);
2253
2254
2255 /**
2256 * @ingroup UCP_MEM
2257 * @brief list of UCP memory use advice.
2258 *
2259 * The enumeration list describes memory advice supported by @ref
2260 * ucp_mem_advise() function.
2261 */
2262 typedef enum ucp_mem_advice {
2263 UCP_MADV_NORMAL = 0, /**< No special treatment */
2264 UCP_MADV_WILLNEED /**< can be used on the memory mapped with
2265 @ref UCP_MEM_MAP_NONBLOCK to speed up memory
2266 mapping and to avoid page faults when
2267 the memory is accessed for the first time. */
2268 } ucp_mem_advice_t;
2269
2270
2271 /**
2272 * @ingroup UCP_MEM
2273 * @brief Tuning parameters for the UCP memory advice.
2274 *
2275 * This structure defines the parameters that are used for the
2276 * UCP memory advice tuning during the @ref ucp_mem_advise "ucp_mem_advise"
2277 * routine.
2278 */
2279 typedef struct ucp_mem_advise_params {
2280 /**
2281 * Mask of valid fields in this structure, using bits from
2282 * @ref ucp_mem_advise_params_field. All fields are mandatory.
2283 * Provides ABI compatibility with respect to adding new fields.
2284 */
2285 uint64_t field_mask;
2286
2287 /**
2288 * Memory base address.
2289 */
2290 void *address;
2291
2292 /**
2293 * Length (in bytes) to allocate or map (register).
2294 */
2295 size_t length;
2296
2297 /**
2298 * Memory use advice @ref ucp_mem_advice
2299 */
2300 ucp_mem_advice_t advice;
2301 } ucp_mem_advise_params_t;
2302
2303
2304 /**
2305 * @ingroup UCP_MEM
2306 * @brief give advice about the use of memory
2307 *
2308 * This routine advises the UCP about how to handle memory range beginning at
2309 * address and size of length bytes. This call does not influence the semantics
2310 * of the application, but may influence its performance. The UCP may ignore
2311 * the advice.
2312 *
2313 * @param [in] context Application @ref ucp_context_h "context" which was
2314 * used to allocate/map the memory.
2315 * @param [in] memh @ref ucp_mem_h "Handle" to memory region.
2316 * @param [in] params Memory base address and length. The advice field
2317 * is used to pass memory use advice as defined in
2318 * the @ref ucp_mem_advice list
2319 * The memory range must belong to the @a memh
2320 *
2321 * @return Error code as defined by @ref ucs_status_t
2322 */
2323 ucs_status_t ucp_mem_advise(ucp_context_h context, ucp_mem_h memh,
2324 ucp_mem_advise_params_t *params);
2325
2326
2327 /**
2328 * @ingroup UCP_MEM
2329 * @brief Pack memory region remote access key.
2330 *
2331 * This routine allocates memory buffer and packs into the buffer
2332 * a remote access key (RKEY) object. RKEY is an opaque object that provides
2333 * the information that is necessary for remote memory access.
2334 * This routine packs the RKEY object in a portable format such that the
2335 * object can be @ref ucp_ep_rkey_unpack "unpacked" on any platform supported by the
2336 * UCP library. In order to release the memory buffer allocated by this routine
2337 * the application is responsible for calling the @ref ucp_rkey_buffer_release
2338 * "ucp_rkey_buffer_release()" routine.
2339 *
2340 *
2341 * @note
2342 * @li RKEYs for InfiniBand and Cray Aries networks typically includes
2343 * InifiniBand and Aries key.
2344 * @li In order to enable remote direct memory access to the memory associated
2345 * with the memory handle the application is responsible for sharing the RKEY with
2346 * the peers that will initiate the access.
2347 *
2348 * @param [in] context Application @ref ucp_context_h "context" which was
2349 * used to allocate/map the memory.
2350 * @param [in] memh @ref ucp_mem_h "Handle" to memory region.
2351 * @param [out] rkey_buffer_p Memory buffer allocated by the library.
2352 * The buffer contains packed RKEY.
2353 * @param [out] size_p Size (in bytes) of the packed RKEY.
2354 *
2355 * @return Error code as defined by @ref ucs_status_t
2356 */
2357 ucs_status_t ucp_rkey_pack(ucp_context_h context, ucp_mem_h memh,
2358 void **rkey_buffer_p, size_t *size_p);
2359
2360
2361 /**
2362 * @ingroup UCP_MEM
2363 * @brief Release packed remote key buffer.
2364 *
2365 * This routine releases the buffer that was allocated using @ref ucp_rkey_pack
2366 * "ucp_rkey_pack()".
2367 *
2368 * @warning
2369 * @li Once memory is released an access to the memory may cause a
2370 * failure.
2371 * @li If the input memory address was not allocated using
2372 * @ref ucp_rkey_pack "ucp_rkey_pack()" routine the behaviour of this routine
2373 * is undefined.
2374 *
2375 * @param [in] rkey_buffer Buffer to release.
2376 */
2377 void ucp_rkey_buffer_release(void *rkey_buffer);
2378
2379
2380 /**
2381 * @ingroup UCP_MEM
2382 * @brief Create remote access key from packed buffer.
2383 *
2384 * This routine unpacks the remote key (RKEY) object into the local memory
2385 * such that it can be accessed and used by UCP routines. The RKEY object has
2386 * to be packed using the @ref ucp_rkey_pack "ucp_rkey_pack()" routine.
2387 * Application code should not make any changes to the content of the RKEY
2388 * buffer.
2389 *
2390 * @note The application is responsible for releasing the RKEY object when
2391 * it is no longer needed, by calling the @ref ucp_rkey_destroy
2392 * "ucp_rkey_destroy()" routine.
2393 * @note The remote key object can be used for communications only on the
2394 * endpoint on which it was unpacked.
2395 *
2396 * @param [in] ep Endpoint to access using the remote key.
2397 * @param [in] rkey_buffer Packed rkey.
2398 * @param [out] rkey_p Remote key handle.
2399 *
2400 * @return Error code as defined by @ref ucs_status_t
2401 */
2402 ucs_status_t ucp_ep_rkey_unpack(ucp_ep_h ep, const void *rkey_buffer,
2403 ucp_rkey_h *rkey_p);
2404
2405
2406 /**
2407 * @ingroup UCP_MEM
2408 * @brief Get a local pointer to remote memory.
2409 *
2410 * This routine returns a local pointer to the remote memory described
2411 * by the rkey.
2412 *
2413 * @note This routine can return a valid pointer only for the endpoints
2414 * that are reachable via shared memory.
2415 *
2416 * @param [in] rkey A remote key handle.
2417 * @param [in] raddr A remote memory address within the memory area
2418 * described by the rkey.
2419 * @param [out] addr_p A pointer that can be used for direct
2420 * access to the remote memory.
2421 *
2422 * @return Error code as defined by @ref ucs_status_t if the remote memory
2423 * cannot be accessed directly or the remote memory address is not valid.
2424 */
2425 ucs_status_t ucp_rkey_ptr(ucp_rkey_h rkey, uint64_t raddr, void **addr_p);
2426
2427
2428 /**
2429 * @ingroup UCP_MEM
2430 * @brief Destroy the remote key
2431 *
2432 * This routine destroys the RKEY object and the memory that was allocated
2433 * using the @ref ucp_ep_rkey_unpack "ucp_ep_rkey_unpack()" routine. This
2434 * routine also releases any resources that are associated with the RKEY
2435 * object.
2436 *
2437 * @warning
2438 * @li Once the RKEY object is released an access to the memory will cause an
2439 * undefined failure.
2440 * @li If the RKEY object was not created using
2441 * @ref ucp_ep_rkey_unpack "ucp_ep_rkey_unpack()" routine the behavior of this
2442 * routine is undefined.
2443 * @li The RKEY object must be destroyed after all outstanding operations which
2444 * are using it are flushed, and before the endpoint on which it was unpacked
2445 * is destroyed.
2446 *
2447 * @param [in] rkey Remote key to destroy.
2448 */
2449 void ucp_rkey_destroy(ucp_rkey_h rkey);
2450
2451
2452 /**
2453 * @ingroup UCP_WORKER
2454 * @brief Add user defined callback for Active Message.
2455 *
2456 * This routine installs a user defined callback to handle incoming Active
2457 * Messages with a specific id. This callback is called whenever an Active
2458 * Message that was sent from the remote peer by @ref ucp_am_send_nb is
2459 * received on this worker.
2460 *
2461 * @param [in] worker UCP worker on which to set the Active Message
2462 * handler.
2463 * @param [in] id Active Message id.
2464 * @param [in] cb Active Message callback. NULL to clear.
2465 * @param [in] arg Active Message argument, which will be passed
2466 * in to every invocation of the callback as the
2467 * arg argument.
2468 * @param [in] flags Dictates how an Active Message is handled on the
2469 * remote endpoint. Currently only
2470 * UCP_AM_FLAG_WHOLE_MSG is supported, which
2471 * indicates the callback will not be invoked
2472 * until all data has arrived.
2473 *
2474 * @return error code if the worker does not support Active Messages or
2475 * requested callback flags.
2476 */
2477 ucs_status_t ucp_worker_set_am_handler(ucp_worker_h worker, uint16_t id,
2478 ucp_am_callback_t cb, void *arg,
2479 uint32_t flags);
2480
2481
2482 /**
2483 * @ingroup UCP_COMM
2484 * @brief Send Active Message.
2485 *
2486 * This routine sends an Active Message to an ep. It does not support
2487 * CUDA memory.
2488 *
2489 * @param [in] ep UCP endpoint where the Active Message will be run.
2490 * @param [in] id Active Message id. Specifies which registered
2491 * callback to run.
2492 * @param [in] buffer Pointer to the data to be sent to the target node
2493 * of the Active Message.
2494 * @param [in] count Number of elements to send.
2495 * @param [in] datatype Datatype descriptor for the elements in the buffer.
2496 * @param [in] cb Callback that is invoked upon completion of the
2497 * data transfer if it is not completed immediately.
2498 * @param [in] flags For Future use.
2499 *
2500 * @return NULL Active Message was sent immediately.
2501 * @return UCS_PTR_IS_ERR(_ptr) Error sending Active Message.
2502 * @return otherwise Pointer to request, and Active Message is known
2503 * to be completed after cb is run.
2504 */
2505 ucs_status_ptr_t ucp_am_send_nb(ucp_ep_h ep, uint16_t id,
2506 const void *buffer, size_t count,
2507 ucp_datatype_t datatype,
2508 ucp_send_callback_t cb, unsigned flags);
2509
2510
2511 /**
2512 * @ingroup UCP_COMM
2513 * @brief Releases Active Message data.
2514 *
2515 * This routine releases data that persisted through an Active Message
2516 * callback because that callback returned UCS_INPROGRESS.
2517 *
2518 * @param [in] worker Worker which received the Active Message.
2519 * @param [in] data Pointer to data that was passed into
2520 * the Active Message callback as the data
2521 * parameter.
2522 */
2523 void ucp_am_data_release(ucp_worker_h worker, void *data);
2524
2525
2526 /**
2527 * @ingroup UCP_COMM
2528 * @brief Non-blocking stream send operation.
2529 *
2530 * This routine sends data that is described by the local address @a buffer,
2531 * size @a count, and @a datatype object to the destination endpoint @a ep.
2532 * The routine is non-blocking and therefore returns immediately, however
2533 * the actual send operation may be delayed. The send operation is considered
2534 * completed when it is safe to reuse the source @e buffer. If the send
2535 * operation is completed immediately the routine returns UCS_OK and the
2536 * call-back function @a cb is @b not invoked. If the operation is
2537 * @b not completed immediately and no error reported, then the UCP library will
2538 * schedule invocation of the call-back @a cb upon completion of the send
2539 * operation. In other words, the completion of the operation will be signaled
2540 * either by the return code or by the call-back.
2541 *
2542 * @note The user should not modify any part of the @a buffer after this
2543 * operation is called, until the operation completes.
2544 *
2545 * @param [in] ep Destination endpoint handle.
2546 * @param [in] buffer Pointer to the message buffer (payload).
2547 * @param [in] count Number of elements to send.
2548 * @param [in] datatype Datatype descriptor for the elements in the buffer.
2549 * @param [in] cb Callback function that is invoked whenever the
2550 * send operation is completed. It is important to note
2551 * that the call-back is only invoked in a case when
2552 * the operation cannot be completed in place.
2553 * @param [in] flags Reserved for future use.
2554 *
2555 * @return NULL - The send operation was completed immediately.
2556 * @return UCS_PTR_IS_ERR(_ptr) - The send operation failed.
2557 * @return otherwise - Operation was scheduled for send and can be
2558 * completed in any point in time. The request handle
2559 * is returned to the application in order to track
2560 * progress of the message. The application is
2561 * responsible for releasing the handle using
2562 * @ref ucp_request_free routine.
2563 */
2564 ucs_status_ptr_t ucp_stream_send_nb(ucp_ep_h ep, const void *buffer, size_t count,
2565 ucp_datatype_t datatype, ucp_send_callback_t cb,
2566 unsigned flags);
2567
2568
2569 /**
2570 * @ingroup UCP_COMM
2571 * @brief Non-blocking stream send operation.
2572 *
2573 * This routine sends data that is described by the local address @a buffer,
2574 * size @a count object to the destination endpoint @a ep. The routine is
2575 * non-blocking and therefore returns immediately, however the actual send
2576 * operation may be delayed. The send operation is considered completed when
2577 * it is safe to reuse the source @e buffer. If the send operation is
2578 * completed immediately the routine returns UCS_OK.
2579 *
2580 * @note The user should not modify any part of the @a buffer after this
2581 * operation is called, until the operation completes.
2582 *
2583 * @param [in] ep Destination endpoint handle.
2584 * @param [in] buffer Pointer to the message buffer (payload).
2585 * @param [in] count Number of elements to send.
2586 * @param [in] param Operation parameters, see @ref ucp_request_param_t.
2587 *
2588 * @return NULL - The send operation was completed immediately.
2589 * @return UCS_PTR_IS_ERR(_ptr) - The send operation failed.
2590 * @return otherwise - Operation was scheduled for send and can be
2591 * completed at any point in time. The request
2592 * handle is returned to the application in
2593 * order to track progress of the message.
2594 */
2595 ucs_status_ptr_t ucp_stream_send_nbx(ucp_ep_h ep, const void *buffer, size_t count,
2596 const ucp_request_param_t *param);
2597
2598
2599 /**
2600 * @ingroup UCP_COMM
2601 * @brief Non-blocking tagged-send operations
2602 *
2603 * This routine sends a messages that is described by the local address @a
2604 * buffer, size @a count, and @a datatype object to the destination endpoint
2605 * @a ep. Each message is associated with a @a tag value that is used for
2606 * message matching on the @ref ucp_tag_recv_nb "receiver". The routine is
2607 * non-blocking and therefore returns immediately, however the actual send
2608 * operation may be delayed. The send operation is considered completed when
2609 * it is safe to reuse the source @e buffer. If the send operation is
2610 * completed immediately the routine return UCS_OK and the call-back function
2611 * @a cb is @b not invoked. If the operation is @b not completed immediately
2612 * and no error reported then the UCP library will schedule to invoke the
2613 * call-back @a cb whenever the send operation will be completed. In other
2614 * words, the completion of a message can be signaled by the return code or
2615 * the call-back.
2616 *
2617 * @note The user should not modify any part of the @a buffer after this
2618 * operation is called, until the operation completes.
2619 *
2620 * @param [in] ep Destination endpoint handle.
2621 * @param [in] buffer Pointer to the message buffer (payload).
2622 * @param [in] count Number of elements to send
2623 * @param [in] datatype Datatype descriptor for the elements in the buffer.
2624 * @param [in] tag Message tag.
2625 * @param [in] cb Callback function that is invoked whenever the
2626 * send operation is completed. It is important to note
2627 * that the call-back is only invoked in a case when
2628 * the operation cannot be completed in place.
2629 *
2630 * @return NULL - The send operation was completed immediately.
2631 * @return UCS_PTR_IS_ERR(_ptr) - The send operation failed.
2632 * @return otherwise - Operation was scheduled for send and can be
2633 * completed in any point in time. The request handle
2634 * is returned to the application in order to track
2635 * progress of the message. The application is
2636 * responsible for releasing the handle using
2637 * @ref ucp_request_free "ucp_request_free()" routine.
2638 */
2639 ucs_status_ptr_t ucp_tag_send_nb(ucp_ep_h ep, const void *buffer, size_t count,
2640 ucp_datatype_t datatype, ucp_tag_t tag,
2641 ucp_send_callback_t cb);
2642
2643 /**
2644 * @ingroup UCP_COMM
2645 * @brief Non-blocking tagged-send operations with user provided request
2646 *
2647 * This routine provides a convenient and efficient way to implement a
2648 * blocking send pattern. It also completes requests faster than
2649 * @ref ucp_tag_send_nb() because:
2650 * @li it always uses @ref uct_ep_am_bcopy() to send data up to the
2651 * rendezvous threshold.
2652 * @li its rendezvous threshold is higher than the one used by
2653 * the @ref ucp_tag_send_nb(). The threshold is controlled by
2654 * the @b UCX_SEND_NBR_RNDV_THRESH environment variable.
2655 * @li its request handling is simpler. There is no callback and no need
2656 * to allocate and free requests. In fact request can be allocated by
2657 * caller on the stack.
2658 *
2659 * This routine sends a messages that is described by the local address @a
2660 * buffer, size @a count, and @a datatype object to the destination endpoint
2661 * @a ep. Each message is associated with a @a tag value that is used for
2662 * message matching on the @ref ucp_tag_recv_nbr "receiver".
2663 *
2664 * The routine is non-blocking and therefore returns immediately, however
2665 * the actual send operation may be delayed. The send operation is considered
2666 * completed when it is safe to reuse the source @e buffer. If the send
2667 * operation is completed immediately the routine returns UCS_OK.
2668 *
2669 * If the operation is @b not completed immediately and no error reported
2670 * then the UCP library will fill a user provided @a req and
2671 * return UCS_INPROGRESS status. In order to monitor completion of the
2672 * operation @ref ucp_request_check_status() should be used.
2673 *
2674 * Following pseudo code implements a blocking send function:
2675 * @code
2676 * MPI_send(...)
2677 * {
2678 * char *request;
2679 * ucs_status_t status;
2680 *
2681 * // allocate request on the stack
2682 * // ucp_context_query() was used to get ucp_request_size
2683 * request = alloca(ucp_request_size);
2684 *
2685 * // note: make sure that there is enough memory before the
2686 * // request handle
2687 * status = ucp_tag_send_nbr(ep, ..., request + ucp_request_size);
2688 * if (status != UCS_INPROGRESS) {
2689 * return status;
2690 * }
2691 *
2692 * do {
2693 * ucp_worker_progress(worker);
2694 * status = ucp_request_check_status(request + ucp_request_size);
2695 * } while (status == UCS_INPROGRESS);
2696 *
2697 * return status;
2698 * }
2699 * @endcode
2700 *
2701 * @note The user should not modify any part of the @a buffer after this
2702 * operation is called, until the operation completes.
2703 *
2704 *
2705 * @param [in] ep Destination endpoint handle.
2706 * @param [in] buffer Pointer to the message buffer (payload).
2707 * @param [in] count Number of elements to send
2708 * @param [in] datatype Datatype descriptor for the elements in the buffer.
2709 * @param [in] tag Message tag.
2710 * @param [in] req Request handle allocated by the user. There should
2711 * be at least UCP request size bytes of available
2712 * space before the @a req. The size of UCP request
2713 * can be obtained by @ref ucp_context_query function.
2714 *
2715 * @return UCS_OK - The send operation was completed immediately.
2716 * @return UCS_INPROGRESS - The send was not completed and is in progress.
2717 * @ref ucp_request_check_status() should be used to
2718 * monitor @a req status.
2719 * @return Error code as defined by @ref ucs_status_t
2720 */
2721 ucs_status_t ucp_tag_send_nbr(ucp_ep_h ep, const void *buffer, size_t count,
2722 ucp_datatype_t datatype, ucp_tag_t tag, void *req);
2723
2724 /**
2725 * @ingroup UCP_COMM
2726 * @brief Non-blocking synchronous tagged-send operation.
2727 *
2728 * Same as @ref ucp_tag_send_nb, except the request completes only after there
2729 * is a remote tag match on the message (which does not always mean the remote
2730 * receive has been completed). This function never completes "in-place", and
2731 * always returns a request handle.
2732 *
2733 * @note The user should not modify any part of the @a buffer after this
2734 * operation is called, until the operation completes.
2735 * @note Returns @ref UCS_ERR_UNSUPPORTED if @ref UCP_ERR_HANDLING_MODE_PEER is
2736 * enabled. This is a temporary implementation-related constraint that
2737 * will be addressed in future releases.
2738 *
2739 * @param [in] ep Destination endpoint handle.
2740 * @param [in] buffer Pointer to the message buffer (payload).
2741 * @param [in] count Number of elements to send
2742 * @param [in] datatype Datatype descriptor for the elements in the buffer.
2743 * @param [in] tag Message tag.
2744 * @param [in] cb Callback function that is invoked whenever the
2745 * send operation is completed.
2746 *
2747 * @return UCS_PTR_IS_ERR(_ptr) - The send operation failed.
2748 * @return otherwise - Operation was scheduled for send and can be
2749 * completed in any point in time. The request handle
2750 * is returned to the application in order to track
2751 * progress of the message. The application is
2752 * responsible for releasing the handle using
2753 * @ref ucp_request_free "ucp_request_free()" routine.
2754 */
2755 ucs_status_ptr_t ucp_tag_send_sync_nb(ucp_ep_h ep, const void *buffer, size_t count,
2756 ucp_datatype_t datatype, ucp_tag_t tag,
2757 ucp_send_callback_t cb);
2758
2759
2760 /**
2761 * @ingroup UCP_COMM
2762 * @brief Non-blocking tagged-send operation
2763 *
2764 * This routine sends a messages that is described by the local address @a
2765 * buffer, size @a count object to the destination endpoint @a ep. Each
2766 * message is associated with a @a tag value that is used for message
2767 * matching on the @ref ucp_tag_recv_nb or @ref ucp_tag_recv_nbx "receiver".
2768 * The routine is non-blocking and therefore returns immediately, however the
2769 * actual send operation may be delayed. The send operation is considered
2770 * completed when it is safe to reuse the source @e buffer. If the send
2771 * operation is completed immediately the routine returns UCS_OK and the
2772 * call-back function is @b not invoked. If the operation is @b not completed
2773 * immediately and no error reported then the UCP library will schedule to
2774 * invoke the call-back whenever the send operation is completed. In other
2775 * words, the completion of a message can be signaled by the return code or
2776 * the call-back.
2777 * Immediate completion signals can be fine-tuned via the
2778 * @ref ucp_request_param_t.op_attr_mask field in the
2779 * @ref ucp_request_param_t structure. The values of this field
2780 * are a bit-wise OR of the @ref ucp_op_attr_t enumeration.
2781 *
2782 * @note The user should not modify any part of the @a buffer after this
2783 * operation is called, until the operation completes.
2784 *
2785 * @param [in] ep Destination endpoint handle.
2786 * @param [in] buffer Pointer to the message buffer (payload).
2787 * @param [in] count Number of elements to send
2788 * @param [in] tag Message tag.
2789 * @param [in] param Operation parameters, see @ref ucp_request_param_t
2790 *
2791 * @return UCS_OK - The send operation was completed immediately.
2792 * @return UCS_PTR_IS_ERR(_ptr) - The send operation failed.
2793 * @return otherwise - Operation was scheduled for send and can be
2794 * completed in any point in time. The request handle
2795 * is returned to the application in order to track
2796 * progress of the message.
2797 */
2798 ucs_status_ptr_t ucp_tag_send_nbx(ucp_ep_h ep, const void *buffer, size_t count,
2799 ucp_tag_t tag, const ucp_request_param_t *param);
2800
2801
2802 /**
2803 * @ingroup UCP_COMM
2804 * @brief Non-blocking synchronous tagged-send operation.
2805 *
2806 * Same as @ref ucp_tag_send_nbx, except the request completes only after there
2807 * is a remote tag match on the message (which does not always mean the remote
2808 * receive has been completed). This function never completes "in-place", and
2809 * always returns a request handle.
2810 *
2811 * @note The user should not modify any part of the @a buffer after this
2812 * operation is called, until the operation completes.
2813 * @note Returns @ref UCS_ERR_UNSUPPORTED if @ref UCP_ERR_HANDLING_MODE_PEER is
2814 * enabled. This is a temporary implementation-related constraint that
2815 * will be addressed in future releases.
2816 *
2817 * @param [in] ep Destination endpoint handle.
2818 * @param [in] buffer Pointer to the message buffer (payload).
2819 * @param [in] count Number of elements to send
2820 * @param [in] tag Message tag.
2821 * @param [in] param Operation parameters, see @ref ucp_request_param_t
2822 *
2823 * @return UCS_OK - The send operation was completed immediately.
2824 * @return UCS_PTR_IS_ERR(_ptr) - The send operation failed.
2825 * @return otherwise - Operation was scheduled for send and can be
2826 * completed in any point in time. The request handle
2827 * is returned to the application in order to track
2828 * progress of the message.
2829 */
2830 ucs_status_ptr_t ucp_tag_send_sync_nbx(ucp_ep_h ep, const void *buffer,
2831 size_t count, ucp_tag_t tag,
2832 const ucp_request_param_t *param);
2833
2834
2835 /**
2836 * @ingroup UCP_COMM
2837 * @brief Non-blocking stream receive operation of structured data into a
2838 * user-supplied buffer.
2839 *
2840 * This routine receives data that is described by the local address @a buffer,
2841 * size @a count, and @a datatype object on the endpoint @a ep. The routine is
2842 * non-blocking and therefore returns immediately. The receive operation is
2843 * considered complete when the message is delivered to the buffer. If data is
2844 * not immediately available, the operation will be scheduled for receive and
2845 * a request handle will be returned. In order to notify the application about
2846 * completion of a scheduled receive operation, the UCP library will invoke
2847 * the call-back @a cb when data is in the receive buffer and ready for
2848 * application access. If the receive operation cannot be started, the routine
2849 * returns an error.
2850 *
2851 * @param [in] ep UCP endpoint that is used for the receive operation.
2852 * @param [in] buffer Pointer to the buffer to receive the data to.
2853 * @param [in] count Number of elements to receive into @a buffer.
2854 * @param [in] datatype Datatype descriptor for the elements in the buffer.
2855 * @param [in] cb Callback function that is invoked whenever the
2856 * receive operation is completed and the data is ready
2857 * in the receive @a buffer. It is important to note
2858 * that the call-back is only invoked in a case when
2859 * the operation cannot be completed immediately.
2860 * @param [out] length Size of the received data in bytes. The value is
2861 * valid only if return code is UCS_OK.
2862 * @note The amount of data received, in bytes, is always an
2863 * integral multiple of the @a datatype size.
2864 * @param [in] flags Flags defined in @ref ucp_stream_recv_flags_t.
2865 *
2866 * @return NULL - The receive operation was completed
2867 * immediately.
2868 * @return UCS_PTR_IS_ERR(_ptr) - The receive operation failed.
2869 * @return otherwise - Operation was scheduled for receive. A request
2870 * handle is returned to the application in order
2871 * to track progress of the operation.
2872 * The application is responsible for releasing
2873 * the handle by calling the
2874 * @ref ucp_request_free routine.
2875 */
2876 ucs_status_ptr_t ucp_stream_recv_nb(ucp_ep_h ep, void *buffer, size_t count,
2877 ucp_datatype_t datatype,
2878 ucp_stream_recv_callback_t cb,
2879 size_t *length, unsigned flags);
2880
2881
2882 /**
2883 * @ingroup UCP_COMM
2884 * @brief Non-blocking stream receive operation of structured data into a
2885 * user-supplied buffer.
2886 *
2887 * This routine receives data that is described by the local address @a buffer,
2888 * size @a count object on the endpoint @a ep. The routine is non-blocking
2889 * and therefore returns immediately. The receive operation is considered
2890 * complete when the message is delivered to the buffer. If the receive
2891 * operation cannot be started, the routine returns an error.
2892 *
2893 * @param [in] ep UCP endpoint that is used for the receive operation.
2894 * @param [in] buffer Pointer to the buffer that will receive the data.
2895 * @param [in] count Number of elements to receive into @a buffer.
2896 * @param [out] length Size of the received data in bytes. The value is
2897 * valid only if return code is NULL.
2898 * @param [in] param Operation parameters, see @ref ucp_request_param_t.
2899 * This operation supports specific flags, which can be
2900 * passed in @a param by @ref ucp_request_param_t.flags.
2901 * The exact set of flags is defined by
2902 * @ref ucp_stream_recv_flags_t.
2903 *
2904 * @return NULL - The receive operation was completed
2905 * immediately. In this case the value pointed by
2906 * @a length is updated by the size of received
2907 * data.
2908 * @return UCS_PTR_IS_ERR(_ptr) - The receive operation failed.
2909 * @return otherwise - Operation was scheduled for receive. A request
2910 * handle is returned to the application in order
2911 * to track progress of the operation.
2912 *
2913 * @note The amount of data received, in bytes, is always an integral multiple
2914 * of the @a datatype size.
2915 */
2916 ucs_status_ptr_t ucp_stream_recv_nbx(ucp_ep_h ep, void *buffer, size_t count,
2917 size_t *length,
2918 const ucp_request_param_t *param);
2919
2920
2921 /**
2922 * @ingroup UCP_COMM
2923 * @brief Non-blocking stream receive operation of unstructured data into
2924 * a UCP-supplied buffer.
2925 *
2926 * This routine receives any available data from endpoint @a ep.
2927 * Unlike @ref ucp_stream_recv_nb, the returned data is unstructured and is
2928 * treated as an array of bytes. If data is immediately available,
2929 * UCS_STATUS_PTR(_ptr) is returned as a pointer to the data, and @a length
2930 * is set to the size of the returned data buffer. The routine is non-blocking
2931 * and therefore returns immediately.
2932 *
2933 * @param [in] ep UCP endpoint that is used for the receive
2934 * operation.
2935 * @param [out] length Length of received data.
2936 *
2937 * @return NULL - No received data available on the @a ep.
2938 * @return UCS_PTR_IS_ERR(_ptr) - the receive operation failed and
2939 * UCS_PTR_STATUS(_ptr) indicates an error.
2940 * @return otherwise - The pointer to the data UCS_STATUS_PTR(_ptr)
2941 * is returned to the application. After the data
2942 * is processed, the application is responsible
2943 * for releasing the data buffer by calling the
2944 * @ref ucp_stream_data_release routine.
2945 *
2946 * @note This function returns packed data (equivalent to ucp_dt_make_contig(1)).
2947 * @note This function returns a pointer to a UCP-supplied buffer, whereas
2948 * @ref ucp_stream_recv_nb places the data into a user-provided buffer.
2949 * In some cases, receiving data directly into a UCP-supplied buffer can
2950 * be more optimal, for example by processing the incoming data in-place
2951 * and thus avoiding extra memory copy operations.
2952 */
2953 ucs_status_ptr_t ucp_stream_recv_data_nb(ucp_ep_h ep, size_t *length);
2954
2955
2956 /**
2957 * @ingroup UCP_COMM
2958 * @brief Non-blocking tagged-receive operation.
2959 *
2960 * This routine receives a message that is described by the local address @a
2961 * buffer, size @a count, and @a datatype object on the @a worker. The tag
2962 * value of the receive message has to match the @a tag and @a tag_mask values,
2963 * where the @a tag_mask indicates which bits of the tag have to be matched. The
2964 * routine is non-blocking and therefore returns immediately. The receive
2965 * operation is considered completed when the message is delivered to the @a
2966 * buffer. In order to notify the application about completion of the receive
2967 * operation the UCP library will invoke the call-back @a cb when the received
2968 * message is in the receive buffer and ready for application access. If the
2969 * receive operation cannot be stated the routine returns an error.
2970 *
2971 * @note This routine cannot return UCS_OK. It always returns a request
2972 * handle or an error.
2973 *
2974 * @param [in] worker UCP worker that is used for the receive operation.
2975 * @param [in] buffer Pointer to the buffer to receive the data to.
2976 * @param [in] count Number of elements to receive
2977 * @param [in] datatype Datatype descriptor for the elements in the buffer.
2978 * @param [in] tag Message tag to expect.
2979 * @param [in] tag_mask Bit mask that indicates the bits that are used for
2980 * the matching of the incoming tag
2981 * against the expected tag.
2982 * @param [in] cb Callback function that is invoked whenever the
2983 * receive operation is completed and the data is ready
2984 * in the receive @a buffer.
2985 *
2986 * @return UCS_PTR_IS_ERR(_ptr) - The receive operation failed.
2987 * @return otherwise - Operation was scheduled for receive. The request
2988 * handle is returned to the application in order
2989 * to track progress of the operation. The
2990 * application is responsible for releasing the
2991 * handle using @ref ucp_request_free
2992 * "ucp_request_free()" routine.
2993 */
2994 ucs_status_ptr_t ucp_tag_recv_nb(ucp_worker_h worker, void *buffer, size_t count,
2995 ucp_datatype_t datatype, ucp_tag_t tag,
2996 ucp_tag_t tag_mask, ucp_tag_recv_callback_t cb);
2997
2998
2999 /**
3000 * @ingroup UCP_COMM
3001 * @brief Non-blocking tagged-receive operation.
3002 *
3003 * This routine receives a message that is described by the local address @a
3004 * buffer, size @a count, and @a datatype object on the @a worker. The tag
3005 * value of the receive message has to match the @a tag and @a tag_mask values,
3006 * where the @a tag_mask indicates which bits of the tag have to be matched. The
3007 * routine is non-blocking and therefore returns immediately. The receive
3008 * operation is considered completed when the message is delivered to the @a
3009 * buffer. In order to monitor completion of the operation
3010 * @ref ucp_request_check_status or @ref ucp_tag_recv_request_test should be
3011 * used.
3012 *
3013 * @param [in] worker UCP worker that is used for the receive operation.
3014 * @param [in] buffer Pointer to the buffer to receive the data to.
3015 * @param [in] count Number of elements to receive
3016 * @param [in] datatype Datatype descriptor for the elements in the buffer.
3017 * @param [in] tag Message tag to expect.
3018 * @param [in] tag_mask Bit mask that indicates the bits that are used for
3019 * the matching of the incoming tag
3020 * against the expected tag.
3021 * @param [in] req Request handle allocated by the user. There should
3022 * be at least UCP request size bytes of available
3023 * space before the @a req. The size of UCP request
3024 * can be obtained by @ref ucp_context_query function.
3025 *
3026 * @return Error code as defined by @ref ucs_status_t
3027 */
3028 ucs_status_t ucp_tag_recv_nbr(ucp_worker_h worker, void *buffer, size_t count,
3029 ucp_datatype_t datatype, ucp_tag_t tag,
3030 ucp_tag_t tag_mask, void *req);
3031
3032
3033 /**
3034 * @ingroup UCP_COMM
3035 * @brief Non-blocking tagged-receive operation.
3036 *
3037 * This routine receives a message that is described by the local address @a
3038 * buffer, size @a count, and @a info object on the @a worker. The tag
3039 * value of the receive message has to match the @a tag and @a tag_mask values,
3040 * where the @a tag_mask indicates what bits of the tag have to be matched. The
3041 * routine is a non-blocking and therefore returns immediately. The receive
3042 * operation is considered completed when the message is delivered to the @a
3043 * buffer. In order to notify the application about completion of the receive
3044 * operation the UCP library will invoke the call-back @a cb when the received
3045 * message is in the receive buffer and ready for application access. If the
3046 * receive operation cannot be stated the routine returns an error.
3047 *
3048 * @note This routine cannot return UCS_OK. It always returns a request
3049 * handle or an error.
3050 *
3051 * @param [in] worker UCP worker that is used for the receive operation.
3052 * @param [in] buffer Pointer to the buffer to receive the data to.
3053 * @param [in] count Number of elements to receive
3054 * @param [in] tag Message tag to expect.
3055 * @param [in] tag_mask Bit mask that indicates the bits that are used for
3056 * the matching of the incoming tag
3057 * against the expected tag.
3058 * @param [in] param Operation parameters, see @ref ucp_request_param_t
3059 *
3060 * @return UCS_PTR_IS_ERR(_ptr) - The receive operation failed.
3061 * @return otherwise - Operation was scheduled for receive. The request
3062 * handle is returned to the application in order
3063 * to track progress of the operation. The
3064 * application is responsible for releasing the
3065 * handle using @ref ucp_request_free
3066 * "ucp_request_free()" routine.
3067 */
3068 ucs_status_ptr_t ucp_tag_recv_nbx(ucp_worker_h worker, void *buffer, size_t count,
3069 ucp_tag_t tag, ucp_tag_t tag_mask,
3070 const ucp_request_param_t *param);
3071
3072
3073 /**
3074 * @ingroup UCP_COMM
3075 * @brief Non-blocking probe and return a message.
3076 *
3077 * This routine probes (checks) if a messages described by the @a tag and
3078 * @a tag_mask was received (fully or partially) on the @a worker. The tag
3079 * value of the received message has to match the @a tag and @a tag_mask
3080 * values, where the @a tag_mask indicates what bits of the tag have to be
3081 * matched. The function returns immediately and if the message is matched it
3082 * returns a handle for the message.
3083 *
3084 * @param [in] worker UCP worker that is used for the probe operation.
3085 * @param [in] tag Message tag to probe for.
3086 * @param [in] tag_mask Bit mask that indicates the bits that are used for
3087 * the matching of the incoming tag
3088 * against the expected tag.
3089 * @param [in] remove The flag indicates if the matched message has to
3090 * be removed from UCP library.
3091 * If true (1), the message handle is removed from
3092 * the UCP library and the application is responsible
3093 * to call @ref ucp_tag_msg_recv_nb
3094 * "ucp_tag_msg_recv_nb()" in order to receive the data
3095 * and release the resources associated with the
3096 * message handle.
3097 * If false (0), the return value is merely an indication
3098 * to whether a matching message is present, and it cannot
3099 * be used in any other way, and in particular it cannot
3100 * be passed to @ref ucp_tag_msg_recv_nb().
3101 * @param [out] info If the matching message is found the descriptor is
3102 * filled with the details about the message.
3103 *
3104 * @return NULL - No match found.
3105 * @return Message handle (not NULL) - If message is matched the message handle
3106 * is returned.
3107 *
3108 * @note This function does not advance the communication state of the network.
3109 * If this routine is used in busy-poll mode, need to make sure
3110 * @ref ucp_worker_progress() is called periodically to extract messages
3111 * from the transport.
3112 */
3113 ucp_tag_message_h ucp_tag_probe_nb(ucp_worker_h worker, ucp_tag_t tag,
3114 ucp_tag_t tag_mask, int remove,
3115 ucp_tag_recv_info_t *info);
3116
3117
3118 /**
3119 * @ingroup UCP_COMM
3120 * @brief Non-blocking receive operation for a probed message.
3121 *
3122 * This routine receives a message that is described by the local address @a
3123 * buffer, size @a count, @a message handle, and @a datatype object on the @a
3124 * worker. The @a message handle can be obtained by calling the @ref
3125 * ucp_tag_probe_nb "ucp_tag_probe_nb()" routine. @ref ucp_tag_msg_recv_nb
3126 * "ucp_tag_msg_recv_nb()" routine is non-blocking and therefore returns
3127 * immediately. The receive operation is considered completed when the message
3128 * is delivered to the @a buffer. In order to notify the application about
3129 * completion of the receive operation the UCP library will invoke the
3130 * call-back @a cb when the received message is in the receive buffer and ready
3131 * for application access. If the receive operation cannot be started the
3132 * routine returns an error.
3133 *
3134 * @param [in] worker UCP worker that is used for the receive operation.
3135 * @param [in] buffer Pointer to the buffer to receive the data to.
3136 * @param [in] count Number of elements to receive
3137 * @param [in] datatype Datatype descriptor for the elements in the buffer.
3138 * @param [in] message Message handle.
3139 * @param [in] cb Callback function that is invoked whenever the
3140 * receive operation is completed and the data is ready
3141 * in the receive @a buffer.
3142 *
3143 * @return UCS_PTR_IS_ERR(_ptr) - The receive operation failed.
3144 * @return otherwise - Operation was scheduled for receive. The request
3145 * handle is returned to the application in order
3146 * to track progress of the operation. The
3147 * application is responsible for releasing the
3148 * handle using @ref ucp_request_free
3149 * "ucp_request_free()" routine.
3150 */
3151 ucs_status_ptr_t ucp_tag_msg_recv_nb(ucp_worker_h worker, void *buffer,
3152 size_t count, ucp_datatype_t datatype,
3153 ucp_tag_message_h message,
3154 ucp_tag_recv_callback_t cb);
3155
3156
3157 /**
3158 * @ingroup UCP_COMM
3159 * @brief Non-blocking implicit remote memory put operation.
3160 *
3161 * This routine initiates a storage of contiguous block of data that is
3162 * described by the local address @a buffer in the remote contiguous memory
3163 * region described by @a remote_addr address and the @ref ucp_rkey_h "memory
3164 * handle" @a rkey. The routine returns immediately and @b does @b not
3165 * guarantee re-usability of the source address @e buffer. If the operation is
3166 * completed immediately the routine return UCS_OK, otherwise UCS_INPROGRESS
3167 * or an error is returned to user.
3168 *
3169 * @note A user can use @ref ucp_worker_flush_nb "ucp_worker_flush_nb()"
3170 * in order to guarantee re-usability of the source address @e buffer.
3171 *
3172 * @param [in] ep Remote endpoint handle.
3173 * @param [in] buffer Pointer to the local source address.
3174 * @param [in] length Length of the data (in bytes) stored under the
3175 * source address.
3176 * @param [in] remote_addr Pointer to the destination remote memory address
3177 * to write to.
3178 * @param [in] rkey Remote memory key associated with the
3179 * remote memory address.
3180 *
3181 * @return Error code as defined by @ref ucs_status_t
3182 */
3183 ucs_status_t ucp_put_nbi(ucp_ep_h ep, const void *buffer, size_t length,
3184 uint64_t remote_addr, ucp_rkey_h rkey);
3185
3186 /**
3187 * @ingroup UCP_COMM
3188 * @brief Non-blocking remote memory put operation.
3189 *
3190 * This routine initiates a storage of contiguous block of data that is
3191 * described by the local address @a buffer in the remote contiguous memory
3192 * region described by @a remote_addr address and the @ref ucp_rkey_h "memory
3193 * handle" @a rkey. The routine returns immediately and @b does @b not
3194 * guarantee re-usability of the source address @e buffer. If the operation is
3195 * completed immediately the routine return UCS_OK, otherwise UCS_INPROGRESS
3196 * or an error is returned to user. If the put operation completes immediately,
3197 * the routine returns UCS_OK and the call-back routine @a cb is @b not
3198 * invoked. If the operation is @b not completed immediately and no error is
3199 * reported, then the UCP library will schedule invocation of the call-back
3200 * routine @a cb upon completion of the put operation. In other words, the
3201 * completion of a put operation can be signaled by the return code or
3202 * execution of the call-back.
3203 *
3204 * @note A user can use @ref ucp_worker_flush_nb "ucp_worker_flush_nb()"
3205 * in order to guarantee re-usability of the source address @e buffer.
3206 *
3207 * @param [in] ep Remote endpoint handle.
3208 * @param [in] buffer Pointer to the local source address.
3209 * @param [in] length Length of the data (in bytes) stored under the
3210 * source address.
3211 * @param [in] remote_addr Pointer to the destination remote memory address
3212 * to write to.
3213 * @param [in] rkey Remote memory key associated with the
3214 * remote memory address.
3215 * @param [in] cb Call-back function that is invoked whenever the
3216 * put operation is completed and the local buffer
3217 * can be modified. Does not guarantee remote
3218 * completion.
3219 *
3220 * @return NULL - The operation was completed immediately.
3221 * @return UCS_PTR_IS_ERR(_ptr) - The operation failed.
3222 * @return otherwise - Operation was scheduled and can be
3223 * completed at any point in time. The request handle
3224 * is returned to the application in order to track
3225 * progress of the operation. The application is
3226 * responsible for releasing the handle using
3227 * @ref ucp_request_free "ucp_request_free()" routine.
3228 */
3229 ucs_status_ptr_t ucp_put_nb(ucp_ep_h ep, const void *buffer, size_t length,
3230 uint64_t remote_addr, ucp_rkey_h rkey,
3231 ucp_send_callback_t cb);
3232
3233
3234 /**
3235 * @ingroup UCP_COMM
3236 * @brief Non-blocking remote memory put operation.
3237 *
3238 * This routine initiates a storage of contiguous block of data that is
3239 * described by the local address @a buffer in the remote contiguous memory
3240 * region described by @a remote_addr address and the @ref ucp_rkey_h "memory
3241 * handle" @a rkey. The routine returns immediately and @b does @b not
3242 * guarantee re-usability of the source address @e buffer. If the operation is
3243 * completed immediately the routine return UCS_OK, otherwise UCS_INPROGRESS
3244 * or an error is returned to user. If the put operation completes immediately,
3245 * the routine returns UCS_OK and the call-back routine @a param.cb.send is
3246 * @b not invoked. If the operation is @b not completed immediately and no
3247 * error is reported, then the UCP library will schedule invocation of the
3248 * call-back routine @a param.cb.send upon completion of the put operation.
3249 * In other words, the completion of a put operation can be signaled by the
3250 * return code or execution of the call-back.
3251 * Immediate completion signals can be fine-tuned via the
3252 * @ref ucp_request_param_t.op_attr_mask field in the
3253 * @ref ucp_request_param_t structure. The values of this field
3254 * are a bit-wise OR of the @ref ucp_op_attr_t enumeration.
3255 *
3256 * @note A user can use @ref ucp_worker_flush_nb "ucp_worker_flush_nb()"
3257 * in order to guarantee re-usability of the source address @e buffer.
3258 *
3259 * @param [in] ep Remote endpoint handle.
3260 * @param [in] buffer Pointer to the local source address.
3261 * @param [in] count Number of elements of type
3262 * @ref ucp_request_param_t.datatype to put. If
3263 * @ref ucp_request_param_t.datatype is not specified,
3264 * the type defaults to ucp_dt_make_contig(1), which
3265 * corresponds to byte elements.
3266 * @param [in] remote_addr Pointer to the destination remote memory address
3267 * to write to.
3268 * @param [in] rkey Remote memory key associated with the
3269 * remote memory address.
3270 * @param [in] param Operation parameters, see @ref ucp_request_param_t
3271 *
3272 * @return UCS_OK - The operation was completed immediately.
3273 * @return UCS_PTR_IS_ERR(_ptr) - The operation failed.
3274 * @return otherwise - Operation was scheduled and can be
3275 * completed at any point in time. The request handle
3276 * is returned to the application in order to track
3277 * progress of the operation. The application is
3278 * responsible for releasing the handle using
3279 * @ref ucp_request_free "ucp_request_free()" routine.
3280 *
3281 * @note Only the datatype ucp_dt_make_contig(1) is supported
3282 * for @a param->datatype, see @ref ucp_dt_make_contig.
3283 */
3284 ucs_status_ptr_t ucp_put_nbx(ucp_ep_h ep, const void *buffer, size_t count,
3285 uint64_t remote_addr, ucp_rkey_h rkey,
3286 const ucp_request_param_t *param);
3287
3288
3289 /**
3290 * @ingroup UCP_COMM
3291 * @brief Non-blocking implicit remote memory get operation.
3292 *
3293 * This routine initiate a load of contiguous block of data that is described
3294 * by the remote memory address @a remote_addr and the @ref ucp_rkey_h "memory handle"
3295 * @a rkey in the local contiguous memory region described by @a buffer
3296 * address. The routine returns immediately and @b does @b not guarantee that
3297 * remote data is loaded and stored under the local address @e buffer.
3298 *
3299 * @note A user can use @ref ucp_worker_flush_nb "ucp_worker_flush_nb()" in order
3300 * guarantee that remote data is loaded and stored under the local address
3301 * @e buffer.
3302 *
3303 * @param [in] ep Remote endpoint handle.
3304 * @param [in] buffer Pointer to the local destination address.
3305 * @param [in] length Length of the data (in bytes) stored under the
3306 * destination address.
3307 * @param [in] remote_addr Pointer to the source remote memory address
3308 * to read from.
3309 * @param [in] rkey Remote memory key associated with the
3310 * remote memory address.
3311 *
3312 * @return Error code as defined by @ref ucs_status_t
3313 */
3314 ucs_status_t ucp_get_nbi(ucp_ep_h ep, void *buffer, size_t length,
3315 uint64_t remote_addr, ucp_rkey_h rkey);
3316
3317 /**
3318 * @ingroup UCP_COMM
3319 * @brief Non-blocking remote memory get operation.
3320 *
3321 * This routine initiates a load of a contiguous block of data that is
3322 * described by the remote memory address @a remote_addr and the @ref ucp_rkey_h
3323 * "memory handle" @a rkey in the local contiguous memory region described
3324 * by @a buffer address. The routine returns immediately and @b does @b not
3325 * guarantee that remote data is loaded and stored under the local address @e
3326 * buffer. If the operation is completed immediately the routine return UCS_OK,
3327 * otherwise UCS_INPROGRESS or an error is returned to user. If the get
3328 * operation completes immediately, the routine returns UCS_OK and the
3329 * call-back routine @a cb is @b not invoked. If the operation is @b not
3330 * completed immediately and no error is reported, then the UCP library will
3331 * schedule invocation of the call-back routine @a cb upon completion of the
3332 * get operation. In other words, the completion of a get operation can be
3333 * signaled by the return code or execution of the call-back.
3334 *
3335 * @note A user can use @ref ucp_worker_flush_nb "ucp_worker_flush_nb()"
3336 * in order to guarantee re-usability of the source address @e buffer.
3337 *
3338 * @param [in] ep Remote endpoint handle.
3339 * @param [in] buffer Pointer to the local destination address.
3340 * @param [in] length Length of the data (in bytes) stored under the
3341 * destination address.
3342 * @param [in] remote_addr Pointer to the source remote memory address
3343 * to read from.
3344 * @param [in] rkey Remote memory key associated with the
3345 * remote memory address.
3346 * @param [in] cb Call-back function that is invoked whenever the
3347 * get operation is completed and the data is
3348 * visible to the local process.
3349 *
3350 * @return NULL - The operation was completed immediately.
3351 * @return UCS_PTR_IS_ERR(_ptr) - The operation failed.
3352 * @return otherwise - Operation was scheduled and can be
3353 * completed at any point in time. The request handle
3354 * is returned to the application in order to track
3355 * progress of the operation. The application is
3356 * responsible for releasing the handle using
3357 * @ref ucp_request_free "ucp_request_free()" routine.
3358 */
3359 ucs_status_ptr_t ucp_get_nb(ucp_ep_h ep, void *buffer, size_t length,
3360 uint64_t remote_addr, ucp_rkey_h rkey,
3361 ucp_send_callback_t cb);
3362
3363
3364 /**
3365 * @ingroup UCP_COMM
3366 * @brief Non-blocking remote memory get operation.
3367 *
3368 * This routine initiates a load of a contiguous block of data that is
3369 * described by the remote memory address @a remote_addr and the @ref ucp_rkey_h
3370 * "memory handle" @a rkey in the local contiguous memory region described
3371 * by @a buffer address. The routine returns immediately and @b does @b not
3372 * guarantee that remote data is loaded and stored under the local address @e
3373 * buffer. If the operation is completed immediately the routine return UCS_OK,
3374 * otherwise UCS_INPROGRESS or an error is returned to user. If the get
3375 * operation completes immediately, the routine returns UCS_OK and the
3376 * call-back routine @a param.cb.send is @b not invoked. If the operation is
3377 * @b not completed immediately and no error is reported, then the UCP library
3378 * will schedule invocation of the call-back routine @a param.cb.send upon
3379 * completion of the get operation. In other words, the completion of a get
3380 * operation can be signaled by the return code or execution of the call-back.
3381 *
3382 * @note A user can use @ref ucp_worker_flush_nb "ucp_worker_flush_nb()"
3383 * in order to guarantee re-usability of the source address @e buffer.
3384 *
3385 * @param [in] ep Remote endpoint handle.
3386 * @param [in] buffer Pointer to the local destination address.
3387 * @param [in] count Number of elements of type
3388 * @ref ucp_request_param_t.datatype to put. If
3389 * @ref ucp_request_param_t.datatype is not specified,
3390 * the type defaults to ucp_dt_make_contig(1), which
3391 * corresponds to byte elements.
3392 * @param [in] remote_addr Pointer to the source remote memory address
3393 * to read from.
3394 * @param [in] rkey Remote memory key associated with the
3395 * remote memory address.
3396 * @param [in] param Operation parameters, see @ref ucp_request_param_t.
3397 *
3398 * @return UCS_OK - The operation was completed immediately.
3399 * @return UCS_PTR_IS_ERR(_ptr) - The operation failed.
3400 * @return otherwise - Operation was scheduled and can be
3401 * completed at any point in time. The request handle
3402 * is returned to the application in order to track
3403 * progress of the operation. The application is
3404 * responsible for releasing the handle using
3405 * @ref ucp_request_free "ucp_request_free()" routine.
3406 *
3407 * @note Only the datatype ucp_dt_make_contig(1) is supported
3408 * for @a param->datatype, see @ref ucp_dt_make_contig.
3409 */
3410 ucs_status_ptr_t ucp_get_nbx(ucp_ep_h ep, void *buffer, size_t count,
3411 uint64_t remote_addr, ucp_rkey_h rkey,
3412 const ucp_request_param_t *param);
3413
3414
3415 /**
3416 * @ingroup UCP_COMM
3417 * @brief Post an atomic memory operation.
3418 *
3419 * This routine posts an atomic memory operation to a remote value.
3420 * The remote value is described by the combination of the remote
3421 * memory address @a remote_addr and the @ref ucp_rkey_h "remote memory handle"
3422 * @a rkey.
3423 * Return from the function does not guarantee completion. A user must
3424 * call @ref ucp_ep_flush_nb or @ref ucp_worker_flush_nb to guarantee that the
3425 * remote value has been updated.
3426 *
3427 * @param [in] ep UCP endpoint.
3428 * @param [in] opcode One of @ref ucp_atomic_post_op_t.
3429 * @param [in] value Source operand for the atomic operation.
3430 * @param [in] op_size Size of value in bytes
3431 * @param [in] remote_addr Remote address to operate on.
3432 * @param [in] rkey Remote key handle for the remote memory address.
3433 *
3434 * @return Error code as defined by @ref ucs_status_t
3435 */
3436 ucs_status_t ucp_atomic_post(ucp_ep_h ep, ucp_atomic_post_op_t opcode, uint64_t value,
3437 size_t op_size, uint64_t remote_addr, ucp_rkey_h rkey);
3438
3439
3440 /**
3441 * @ingroup UCP_COMM
3442 * @brief Post an atomic fetch operation.
3443 *
3444 * This routine will post an atomic fetch operation to remote memory.
3445 * The remote value is described by the combination of the remote
3446 * memory address @a remote_addr and the @ref ucp_rkey_h "remote memory handle"
3447 * @a rkey.
3448 * The routine is non-blocking and therefore returns immediately. However the
3449 * actual atomic operation may be delayed. The atomic operation is not considered complete
3450 * until the values in remote and local memory are completed. If the atomic operation
3451 * completes immediately, the routine returns UCS_OK and the call-back routine
3452 * @a cb is @b not invoked. If the operation is @b not completed immediately and no
3453 * error is reported, then the UCP library will schedule invocation of the call-back
3454 * routine @a cb upon completion of the atomic operation. In other words, the completion
3455 * of an atomic operation can be signaled by the return code or execution of the call-back.
3456 *
3457 * @note The user should not modify any part of the @a result after this
3458 * operation is called, until the operation completes.
3459 *
3460 * @param [in] ep UCP endpoint.
3461 * @param [in] opcode One of @ref ucp_atomic_fetch_op_t.
3462 * @param [in] value Source operand for atomic operation. In the case of CSWAP
3463 * this is the conditional for the swap. For SWAP this is
3464 * the value to be placed in remote memory.
3465 * @param [inout] result Local memory address to store resulting fetch to.
3466 * In the case of CSWAP the value in result will be
3467 * swapped into the @a remote_addr if the condition
3468 * is true.
3469 * @param [in] op_size Size of value in bytes and pointer type for result
3470 * @param [in] remote_addr Remote address to operate on.
3471 * @param [in] rkey Remote key handle for the remote memory address.
3472 * @param [in] cb Call-back function that is invoked whenever the
3473 * send operation is completed. It is important to note
3474 * that the call-back function is only invoked in a case when
3475 * the operation cannot be completed in place.
3476 *
3477 * @return NULL - The operation was completed immediately.
3478 * @return UCS_PTR_IS_ERR(_ptr) - The operation failed.
3479 * @return otherwise - Operation was scheduled and can be
3480 * completed at any point in time. The request handle
3481 * is returned to the application in order to track
3482 * progress of the operation. The application is
3483 * responsible for releasing the handle using
3484 * @ref ucp_request_free "ucp_request_free()" routine.
3485 */
3486 ucs_status_ptr_t
3487 ucp_atomic_fetch_nb(ucp_ep_h ep, ucp_atomic_fetch_op_t opcode,
3488 uint64_t value, void *result, size_t op_size,
3489 uint64_t remote_addr, ucp_rkey_h rkey,
3490 ucp_send_callback_t cb);
3491
3492
3493 /**
3494 * @ingroup UCP_COMM
3495 * @brief Post an atomic memory operation.
3496 *
3497 * This routine will post an atomic operation to remote memory.
3498 * The remote value is described by the combination of the remote
3499 * memory address @a remote_addr and the @ref ucp_rkey_h "remote memory handle"
3500 * @a rkey. The routine is non-blocking and therefore returns immediately.
3501 * However, the actual atomic operation may be delayed. In order to enable
3502 * fetching semantics for atomic operations user has to specify
3503 * @a param.reply_buffer. Please see @ref atomic_ops "table" below for more
3504 * details.
3505 *
3506 * @note The user should not modify any part of the @a buffer (or also
3507 * @a param->reply_buffer for fetch operations), until the operation
3508 * completes.
3509 * @note Only ucp_dt_make_config(4) and ucp_dt_make_contig(8) are supported
3510 * in @a param->datatype, see @ref ucp_dt_make_contig.
3511 *
3512 * <table>
3513 * <caption id="atomic_ops">Atomic Operations Semantic</caption>
3514 * <tr> <th align="center">Atomic Operation <th align="center">Pseudo code
3515 * <th align="center">X <th align="center">Y <th align="center">Z
3516 * <th align="center">Result
3517 * <tr> <td align="left">@ref UCP_ATOMIC_OP_ADD <td align="left"> Result=Y; Y+=X
3518 * <td align="left">buffer<td align="left">remote_addr<td align="center">-
3519 * <td align="left">param.reply_buffer(optional)
3520 * <tr> <td align="left">@ref UCP_ATOMIC_OP_SWAP <td align="left"> Result=Y; Y=X
3521 * <td align="left">buffer<td align="left">remote_addr <td align="center">-
3522 * <td align="left">param.reply_buffer
3523 * <tr> <td align="left">@ref UCP_ATOMIC_OP_CSWAP
3524 * <td align="left">Result=Y; if (X==Y) then Y=Z<td align="left">buffer
3525 * <td align="left">remote_addr <td align="left">param.reply_buffer
3526 * <td align="left">param.reply_buffer
3527 * <tr> <td align="left">@ref UCP_ATOMIC_OP_AND <td align="left"> Result=Y; Y&=X
3528 * <td align="left">buffer<td align="left">remote_addr <td align="center">-
3529 * <td align="left">param.reply_buffer(optional)
3530 * <tr> <td align="left">@ref UCP_ATOMIC_OP_OR <td align="left"> Result=Y; Y|=X
3531 * <td align="left">buffer<td align="left">remote_addr <td align="center">-
3532 * <td align="left">param.reply_buffer(optional)
3533 * <tr> <td align="left">@ref UCP_ATOMIC_OP_XOR <td align="left"> Result=Y; Y^=X
3534 * <td align="left">buffer<td align="left">remote_addr <td align="center">-
3535 * <td align="left">param.reply_buffer(optional)
3536 * </table>
3537 *
3538 * @param [in] ep UCP endpoint.
3539 * @param [in] opcode One of @ref ucp_atomic_op_t.
3540 * @param [in] buffer Address of operand for the atomic operation. See
3541 * @ref atomic_ops "Atomic Operations Semantic table"
3542 * for exact usage by different atomic operations.
3543 * @param [in] count Number of elements in @a buffer and @a result. The
3544 * size of each element is specified by
3545 * @ref ucp_request_param_t.datatype
3546 * @param [in] remote_addr Remote address to operate on.
3547 * @param [in] rkey Remote key handle for the remote memory address.
3548 * @param [in] param Operation parameters, see @ref ucp_request_param_t.
3549 *
3550 * @return NULL - The operation completed immediately.
3551 * @return UCS_PTR_IS_ERR(_ptr) - The operation failed.
3552 * @return otherwise - Operation was scheduled and can be
3553 * completed at some time in the future. The
3554 * request handle is returned to the application
3555 * in order to track progress of the operation.
3556 */
3557 ucs_status_ptr_t
3558 ucp_atomic_op_nbx(ucp_ep_h ep, ucp_atomic_op_t opcode, const void *buffer,
3559 size_t count, uint64_t remote_addr, ucp_rkey_h rkey,
3560 const ucp_request_param_t *param);
3561
3562
3563 /**
3564 * @ingroup UCP_COMM
3565 * @brief Check the status of non-blocking request.
3566 *
3567 * This routine checks the state of the request and returns its current status.
3568 * Any value different from UCS_INPROGRESS means that request is in a completed
3569 * state.
3570 *
3571 * @param [in] request Non-blocking request to check.
3572 *
3573 * @return Error code as defined by @ref ucs_status_t
3574 */
3575 ucs_status_t ucp_request_check_status(void *request);
3576
3577
3578 /**
3579 * @ingroup UCP_COMM
3580 * @brief Check the status and currently available state of non-blocking request
3581 * returned from @ref ucp_tag_recv_nb routine.
3582 *
3583 * This routine checks the state and returns current status of the request
3584 * returned from @ref ucp_tag_recv_nb routine or the user allocated request
3585 * for @ref ucp_tag_recv_nbr. Any value different from UCS_INPROGRESS means
3586 * that the request is in a completed state.
3587 *
3588 * @param [in] request Non-blocking request to check.
3589 * @param [out] info It is filled with the details about the message
3590 * available at the moment of calling.
3591 *
3592 * @return Error code as defined by @ref ucs_status_t
3593 */
3594 ucs_status_t ucp_tag_recv_request_test(void *request, ucp_tag_recv_info_t *info);
3595
3596
3597 /**
3598 * @ingroup UCP_COMM
3599 * @brief Check the status and currently available state of non-blocking request
3600 * returned from @ref ucp_stream_recv_nb routine.
3601 *
3602 * This routine checks the state and returns current status of the request
3603 * returned from @ref ucp_stream_recv_nb routine. Any value different from
3604 * UCS_INPROGRESS means that the request is in a completed state.
3605 *
3606 * @param [in] request Non-blocking request to check.
3607 * @param [out] length_p The size of the received data in bytes. This value
3608 * is only valid if the status is UCS_OK. If valid, it
3609 * is always an integral multiple of the datatype size
3610 * associated with the request.
3611 *
3612 * @return Error code as defined by @ref ucs_status_t
3613 */
3614 ucs_status_t ucp_stream_recv_request_test(void *request, size_t *length_p);
3615
3616 /**
3617 * @ingroup UCP_COMM
3618 * @brief Cancel an outstanding communications request.
3619 *
3620 * @param [in] worker UCP worker.
3621 * @param [in] request Non-blocking request to cancel.
3622 *
3623 * This routine tries to cancels an outstanding communication request. After
3624 * calling this routine, the @a request will be in completed or canceled (but
3625 * not both) state regardless of the status of the target endpoint associated
3626 * with the communication request. If the request is completed successfully,
3627 * the @ref ucp_send_callback_t "send" or @ref ucp_tag_recv_callback_t
3628 * "receive" completion callbacks (based on the type of the request) will be
3629 * called with the @a status argument of the callback set to UCS_OK, and in a
3630 * case it is canceled the @a status argument is set to UCS_ERR_CANCELED. It is
3631 * important to note that in order to release the request back to the library
3632 * the application is responsible for calling @ref ucp_request_free
3633 * "ucp_request_free()".
3634 */
3635 void ucp_request_cancel(ucp_worker_h worker, void *request);
3636
3637
3638 /**
3639 * @ingroup UCP_COMM
3640 * @brief Release UCP data buffer returned by @ref ucp_stream_recv_data_nb.
3641 *
3642 * @param [in] ep Endpoint @a data received from.
3643 * @param [in] data Data pointer to release, which was returned from
3644 * @ref ucp_stream_recv_data_nb.
3645 *
3646 * This routine releases internal UCP data buffer returned by
3647 * @ref ucp_stream_recv_data_nb when @a data is processed, the application can't
3648 * use this buffer after calling this function.
3649 */
3650 void ucp_stream_data_release(ucp_ep_h ep, void *data);
3651
3652
3653 /**
3654 * @ingroup UCP_COMM
3655 * @brief Release a communications request.
3656 *
3657 * @param [in] request Non-blocking request to release.
3658 *
3659 * This routine releases the non-blocking request back to the library, regardless
3660 * of its current state. Communications operations associated with this request
3661 * will make progress internally, however no further notifications or callbacks
3662 * will be invoked for this request.
3663 */
3664 void ucp_request_free(void *request);
3665
3666
3667 /**
3668 * @ingroup UCP_COMM
3669 * @brief Create an empty communications request.
3670 *
3671 * @param [in] worker UCP worker.
3672 *
3673 * @return Error code as defined by @ref ucs_status_t
3674 *
3675 * This routine creates request which may be used in functions
3676 * @ref ucp_tag_send_nbx, @ref ucp_tag_recv_nbx, etc. The application
3677 * is responsible for releasing the handle using the @ref ucp_request_free
3678 * routine
3679 */
3680 void *ucp_request_alloc(ucp_worker_h worker);
3681
3682
3683 /**
3684 * @ingroup UCP_DATATYPE
3685 * @brief Create a generic datatype.
3686 *
3687 * This routine create a generic datatype object.
3688 * The generic datatype is described by the @a ops @ref ucp_generic_dt_ops_t
3689 * "object" which provides a table of routines defining the operations for
3690 * generic datatype manipulation. Typically, generic datatypes are used for
3691 * integration with datatype engines provided with MPI implementations (MPICH,
3692 * Open MPI, etc).
3693 * The application is responsible for releasing the @a datatype_p object using
3694 * @ref ucp_dt_destroy "ucp_dt_destroy()" routine.
3695 *
3696 * @param [in] ops Generic datatype function table as defined by
3697 * @ref ucp_generic_dt_ops_t .
3698 * @param [in] context Application defined context passed to this
3699 * routine. The context is passed as a parameter
3700 * to the routines in the @a ops table.
3701 * @param [out] datatype_p A pointer to datatype object.
3702 *
3703 * @return Error code as defined by @ref ucs_status_t
3704 */
3705 ucs_status_t ucp_dt_create_generic(const ucp_generic_dt_ops_t *ops, void *context,
3706 ucp_datatype_t *datatype_p);
3707
3708
3709 /**
3710 * @ingroup UCP_DATATYPE
3711 * @brief Destroy a datatype and release its resources.
3712 *
3713 * This routine destroys the @a datatype object and
3714 * releases any resources that are associated with the object.
3715 * The @a datatype object must be allocated using @ref ucp_dt_create_generic
3716 * "ucp_dt_create_generic()" routine.
3717 *
3718 * @warning
3719 * @li Once the @a datatype object is released an access to this object may
3720 * cause an undefined failure.
3721 *
3722 * @param [in] datatype Datatype object to destroy.
3723 */
3724 void ucp_dt_destroy(ucp_datatype_t datatype);
3725
3726
3727 /**
3728 * @ingroup UCP_WORKER
3729 *
3730 * @brief Assures ordering between non-blocking operations
3731 *
3732 * This routine ensures ordering of non-blocking communication operations on
3733 * the @ref ucp_worker_h "UCP worker". Communication operations issued on the
3734 * @a worker prior to this call are guaranteed to be completed before any
3735 * subsequent communication operations to the same @ref ucp_worker_h "worker"
3736 * which follow the call to @ref ucp_worker_fence "fence".
3737 *
3738 * @note The primary difference between @ref ucp_worker_fence "ucp_worker_fence()"
3739 * and the @ref ucp_worker_flush_nb "ucp_worker_flush_nb()" is the fact the fence
3740 * routine does not guarantee completion of the operations on the call return but
3741 * only ensures the order between communication operations. The
3742 * @ref ucp_worker_flush_nb "flush" operation on return guarantees that all
3743 * operations are completed and corresponding memory regions were updated.
3744 *
3745 * @param [in] worker UCP worker.
3746 *
3747 * @return Error code as defined by @ref ucs_status_t
3748 */
3749 ucs_status_t ucp_worker_fence(ucp_worker_h worker);
3750
3751
3752 /**
3753 * @ingroup UCP_WORKER
3754 *
3755 * @brief Flush outstanding AMO and RMA operations on the @ref ucp_worker_h
3756 * "worker"
3757 *
3758 * This routine flushes all outstanding AMO and RMA communications on the
3759 * @ref ucp_worker_h "worker". All the AMO and RMA operations issued on the
3760 * @a worker prior to this call are completed both at the origin and at the
3761 * target when this call returns.
3762 *
3763 * @note For description of the differences between @ref ucp_worker_flush_nb
3764 * "flush" and @ref ucp_worker_fence "fence" operations please see
3765 * @ref ucp_worker_fence "ucp_worker_fence()"
3766 *
3767 * @param [in] worker UCP worker.
3768 * @param [in] flags Flags for flush operation. Reserved for future use.
3769 * @param [in] cb Callback which will be called when the flush operation
3770 * completes.
3771 *
3772 * @return NULL - The flush operation was completed immediately.
3773 * @return UCS_PTR_IS_ERR(_ptr) - The flush operation failed.
3774 * @return otherwise - Flush operation was scheduled and can be completed
3775 * in any point in time. The request handle is returned
3776 * to the application in order to track progress. The
3777 * application is responsible for releasing the handle
3778 * using @ref ucp_request_free "ucp_request_free()"
3779 * routine.
3780 */
3781 ucs_status_ptr_t ucp_worker_flush_nb(ucp_worker_h worker, unsigned flags,
3782 ucp_send_callback_t cb);
3783
3784
3785 /**
3786 * @ingroup UCP_WORKER
3787 *
3788 * @brief Flush outstanding AMO and RMA operations on the @ref ucp_worker_h
3789 * "worker"
3790 *
3791 * This routine flushes all outstanding AMO and RMA communications on the
3792 * @ref ucp_worker_h "worker". All the AMO and RMA operations issued on the
3793 * @a worker prior to this call are completed both at the origin and at the
3794 * target when this call returns.
3795 *
3796 * @note For description of the differences between @ref ucp_worker_flush_nb
3797 * "flush" and @ref ucp_worker_fence "fence" operations please see
3798 * @ref ucp_worker_fence "ucp_worker_fence()"
3799 *
3800 * @param [in] worker UCP worker.
3801 * @param [in] param Operation parameters, see @ref ucp_request_param_t
3802 *
3803 * @return NULL - The flush operation was completed immediately.
3804 * @return UCS_PTR_IS_ERR(_ptr) - The flush operation failed.
3805 * @return otherwise - Flush operation was scheduled and can be
3806 * completed in any point in time. The request
3807 * handle is returned to the application in order
3808 * to track progress.
3809 */
3810 ucs_status_ptr_t ucp_worker_flush_nbx(ucp_worker_h worker,
3811 const ucp_request_param_t *param);
3812
3813
3814 /**
3815 * @example ucp_hello_world.c
3816 * UCP hello world client / server example utility.
3817 */
3818
3819 END_C_DECLS
3820
3821 #endif
3822