1 /* 2 * MTAPI header contains the public MTAPI API and data type definitions. 3 * 4 * This file defines the MTAPI API. it has to be included by any application 5 * using MTAPI. 6 * 7 * \copyright 8 * Copyright (c) 2012, The Multicore Association. 9 * All rights reserved. 10 * Redistribution and use in source and binary forms, with or without 11 * modification, are permitted provided that the following conditions are met: 12 * (1) Redistributions of source code must retain the above copyright notice, 13 * this list of conditions and the following disclaimer. 14 * (2) Redistributions in binary form must reproduce the above copyright 15 * notice, this list of conditions and the following disclaimer in the 16 * documentation and/or other materials provided with the distribution. 17 * (3) Neither the name of the Multicore Association nor the names of its 18 * contributors may be used to endorse or promote products derived from 19 * this software without specific prior written permission. 20 * 21 * \note 22 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 23 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE 26 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 27 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 28 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 29 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 30 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 31 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 32 * POSSIBILITY OF SUCH DAMAGE. 33 */ 34 35 #ifndef EMBB_MTAPI_C_MTAPI_H_ 36 #define EMBB_MTAPI_C_MTAPI_H_ 37 38 /** 39 * \defgroup C_MTAPI MTAPI 40 * \ingroup C 41 * 42 * Multicore Task Management API (MTAPI®). 43 * 44 * MTAPI is an API standardized by the 45 * <a href="http://www.multicore-association.org">Multicore Association</a> 46 * for leveraging task parallelism on a wide range of embedded devices 47 * containing symmetric or asymmetric multicore processors. 48 * A description of the basic terms and concepts is given below. More 49 * information can be found on the website of the 50 * <a href="http://www.multicore-association.org/workgroup/mtapi.php">Multicore 51 Task Management Working Group</a>. 52 * 53 * ## Definitions 54 * 55 * <table> 56 * <tr> 57 * <td>Action</td> 58 * <td>An action is the hardware or software implementation of a job. An 59 * action implemented in software consists of the implementation of an 60 * action function with a predefined signature. Software actions are 61 * registered with the MTAPI runtime and associated with a job. While 62 * executing, an action is also associated with a task and task context. 63 * Hardware implementations of actions must be known a priori in the 64 * MTAPI runtime implementation. There is no standardized way of 65 * registering hardware actions because they are highly 66 * hardware-dependent. Hardware and software actions are referenced by 67 * handles or indirectly through job IDs and job handles.</td> 68 * </tr> 69 * <tr> 70 * <td>Action Function</td> 71 * <td>The executable function of an action, invoked by the 72 * MTAPI runtime when a task is started.</td> 73 * </tr> 74 * <tr> 75 * <td>Affinity</td> 76 * <td>Defines which cores can execute a given action function.</td> 77 * </tr> 78 * <tr> 79 * <td>Blocking</td> 80 * <td>A blocking function does not return until the function completes 81 * successfully or returns with an error.</td> 82 * </tr> 83 * <tr> 84 * <td>Core</td> 85 * <td>A core is an undividable processing element. Two cores can share 86 * resources such as memory or ALUs for hyperthreaded cores. The core 87 * notion is necessary for core affinity, but is 88 * implementation-specific.</td> 89 * </tr> 90 * <tr> 91 * <td>Domain</td> 92 * <td>An implementation of MTAPI includes one or more domains, each with 93 * one or more nodes. The concept of domains is consistent in all 94 * Multicore Association APIs. A domain is comparable to a subnet in a 95 * network or a namespace for unique names and IDs. Domains are 96 * supported by a runtime.</td> 97 * </tr> 98 * <tr> 99 * <td>Handle</td> 100 * <td>An abstract reference to an object on the same node or to an object 101 * managed by another node. A handle is valid only on the node on which 102 * it was requested and generated. A handle is opaque, that is, its 103 * underlying representation is implementation-defined. Handles can be 104 * copied, assigned, and passed as arguments, but the application 105 * should make no other assumptions about the type, representation, or 106 * contents of a handle.</td> 107 * </tr> 108 * <tr> 109 * <td>Job</td> 110 * <td>A job provides a way to reference one or more actions. Jobs are 111 * abstractions of the processing implemented in hardware or software 112 * by actions. Multiple actions can implement the same job based on 113 * different hardware resources (for instance a job can be implemented 114 * by one action on a DSP and by another action on a general purpose 115 * core, or a job can be implemented by both hardware and software 116 * actions). Each job is represented by a domain-wide job ID, or by a 117 * job handle local to a node.</td> 118 * </tr> 119 * <tr> 120 * <td>MCA</td> 121 * <td>The Multicore Association.</td> 122 * </tr> 123 * <tr> 124 * <td>MTAPI</td> 125 * <td>Multicore Task Management API, defined by The Multicore Association. 126 * </td> 127 * </tr> 128 * <tr> 129 * <td>Node</td> 130 * <td>A node represents an independent unit of execution that maps to a 131 * process, thread, thread pool, instance of an operating system, 132 * hardware accelerator, processor core, a cluster of processor cores, 133 * or other abstract processing entity with an independent program 134 * counter. Each node can belong to only one domain. The concept of 135 * nodes is consistent in all Multicore Associations APIs. Code 136 * executed on an MTAPI node shares memory (data) with any other code 137 * executed on the same node.</td> 138 * </tr> 139 * <tr> 140 * <td>Queue</td> 141 * <td>A software or hardware entity in which tasks are enqueued in a 142 * given order. The queue can ensure in-order execution of tasks. 143 * Furthermore, queues might implement other scheduling policies that 144 * can be configured by setting queue attributes.</td> 145 * </tr> 146 * <tr> 147 * <td>Reference</td> 148 * <td>A reference exists when an object or abstract entity has knowledge 149 * or access to another object, without regard to the specific means of 150 * the implementation.</td> 151 * </tr> 152 * <tr> 153 * <td>Resource</td> 154 * <td>A processing core or chip, hardware accelerator, memory region, or 155 * I/O.</td> 156 * </tr> 157 * <tr> 158 * <td>Remote Memory</td> 159 * <td>Memory that cannot be accessed using standard load and store 160 * operations. For example, host memory is remote to a GPU core.</td> 161 * </tr> 162 * <tr> 163 * <td>Runtime System</td> 164 * <td>An MTAPI runtime system (or "runtime") is the underlying 165 * implementation of MTAPI. The core of the runtime system supports 166 * task scheduling and communication with other nodes. Each MTAPI has 167 * an MTAPI runtime system.</td> 168 * </tr> 169 * <tr> 170 * <td>SMP</td> 171 * <td>SMP is short for symmetric multiprocessing, in which two or more 172 * identical processing cores are connected to a shared main memory 173 * and are controlled by a single OS instance.</td> 174 * </tr> 175 * <tr> 176 * <td>Task</td> 177 * <td>A task is the invocation of an action. A task is associated with a 178 * job object, which is associated with one or more actions. A task 179 * may optionally be associated with a task group. A task has 180 * attributes and an internal state. A task begins its lifetime with a 181 * call to mtapi_task_start() or mtapi_task_enqueue(). A task is 182 * referenced by a handle of type mtapi_task_hndl_t. After a task has 183 * started, it is possible to wait for task completion from other 184 * parts of the program. Every task can run exactly once, i.e., the 185 * task cannot be started a second time. (Note that in other contexts, 186 * the term "task" has a different meaning. Some real-time operating 187 * systems use "task" for operating system threads, for example.)</td> 188 * </tr> 189 * <tr> 190 * <td>Task Context</td> 191 * <td>Information about the task, accessible by the corresponding action 192 * function; useful for action code reflection.</td> 193 * </tr> 194 * </table> 195 * 196 * ## The MTAPI Feature Set 197 * 198 * MTAPI supports two programming modes derived from use cases of the working 199 * group members: 200 * - __Tasks__<br> 201 * MTAPI allows a programmer to start tasks and to synchronize on task 202 * completion. Tasks are executed by the runtime system, concurrently to 203 * other tasks that have been started and have not been completed at that 204 * point in time. A task can be implemented by software or by hardware. 205 * Tasks can be started from remote nodes, i.e., the implementation can be 206 * done on one node, but the starting and synchronization of corresponding 207 * tasks can be done on other nodes. The developer decides where to deploy 208 * a task implementation. On the executing node, the runtime system selects 209 * the cores that execute a particular task. This mapping can be influenced 210 * by application-specific attributes. Tasks can start sub-tasks. MTAPI 211 * provides a basic mechanism to pass data to the node that executes a 212 * task, and back to the calling node. 213 * - __Queues__<br> 214 * Explicit queues can be used to control the task scheduling policies for 215 * related tasks. Order-preserving queues ensure that tasks are executed 216 * sequentially in queue order with no subsequent task starting until the 217 * previous one is complete. MTAPI also supports non-order-preserving 218 * queues, allowing control of the scheduling policies of tasks started via 219 * the same queue (queues may offer implementation specific scheduling 220 * policies controlled by implementation specific queue attributes). Even 221 * hardware queues can be associated with queue objects. 222 * 223 * MTAPI also supports the following types of tasks: 224 * - __Single tasks__<br> 225 * Single tasks are the standard case: After a task is started, the 226 * application may wait for completion of the task at a later point in 227 * time. In some cases the application waits for completion of a group of 228 * tasks. In other cases waiting is not required at all. When a 229 * software-implemented task is started, the corresponding code (action 230 * function) is executed once by the MTAPI runtime environment. When a 231 * hardware-implemented task is started, the task execution is triggered 232 * once by the MTAPI runtime system. 233 * - __Multi-instance tasks__<br> 234 * Multi-instance tasks execute the same action multiple times in parallel 235 * (similar to parallel regions in OpenMP or parallel MPI processes). 236 * - __Multiple-implementation tasks / load balancing__<br> 237 * In heterogeneous systems, there could be implementations of the same job 238 * for different types of processor cores, e.g., one general purpose 239 * implementation and a second one for a hardware accelerator. MTAPI allows 240 * attaching multiple actions to a job. The runtime system shall decide 241 * dynamically during runtime, depending on the system load, which action to 242 * utilize. Only one of the alternative actions will be executed. 243 */ 244 245 #include <stdint.h> 246 #include <embb/base/c/core_set.h> 247 #include <embb/base/c/thread.h> 248 249 #ifdef __cplusplus 250 extern "C" { 251 #endif 252 253 254 /* ---- MCA ORGANIZATION IDS ----------------------------------------------- */ 255 256 #define MCA_ORG_ID_PSI 0 /* PolyCore Software, Inc. */ 257 #define MCA_ORG_ID_FSL 1 /* Freescale, Inc. */ 258 #define MCA_ORG_ID_MGC 2 /* Mentor Graphics, Corp. */ 259 #define MCA_ORG_ID_ADI 3 /* Analog Devices */ 260 #define MCA_ORG_ID_SIE 4 /* Siemens */ 261 #define MCA_ORG_ID_EMB 5 /* EMB2 project */ 262 #define MCA_ORG_ID_TBD 6 /* TBD */ 263 264 265 /* ---- BASIC DEFINITIONS -------------------------------------------------- */ 266 267 /** marks input parameters */ 268 #define MTAPI_IN const 269 /** marks output parameters */ 270 #define MTAPI_OUT 271 /** marks in/out parameters */ 272 #define MTAPI_INOUT 273 274 275 /* ---- BASIC DATA TYPES --------------------------------------------------- */ 276 277 /* MCA type definitions */ 278 typedef int mca_int_t; 279 typedef int8_t mca_int8_t; 280 typedef int16_t mca_int16_t; 281 typedef int32_t mca_int32_t; 282 typedef int64_t mca_int64_t; 283 284 typedef unsigned int mca_uint_t; 285 typedef uint8_t mca_uint8_t; 286 typedef uint16_t mca_uint16_t; 287 typedef uint32_t mca_uint32_t; 288 typedef uint64_t mca_uint64_t; 289 290 typedef unsigned char mca_boolean_t; 291 292 typedef unsigned int mca_domain_t; 293 typedef unsigned int mca_node_t; 294 typedef unsigned int mca_status_t; 295 typedef int mca_timeout_t; 296 297 /* the MTAPI data types */ 298 typedef mca_int_t mtapi_int_t; 299 typedef mca_int8_t mtapi_int8_t; 300 typedef mca_int16_t mtapi_int16_t; 301 typedef mca_int32_t mtapi_int32_t; 302 typedef mca_int64_t mtapi_int64_t; 303 304 typedef mca_uint_t mtapi_uint_t; 305 typedef mca_uint8_t mtapi_uint8_t; 306 typedef mca_uint16_t mtapi_uint16_t; 307 typedef mca_uint32_t mtapi_uint32_t; 308 typedef mca_uint64_t mtapi_uint64_t; 309 310 typedef mca_domain_t mtapi_domain_t; 311 typedef mca_node_t mtapi_node_t; 312 typedef mca_timeout_t mtapi_timeout_t; 313 314 typedef mca_boolean_t mtapi_boolean_t; 315 typedef mtapi_uint_t mtapi_size_t; 316 317 /** 318 * Info structure. 319 * \ingroup RUNTIME_INIT_SHUTDOWN 320 */ 321 struct mtapi_info_struct { 322 mtapi_uint_t mtapi_version; /**< The three last (rightmost) hex 323 digits are the minor number, and 324 those left of the minor number are 325 the major number. */ 326 mtapi_uint_t organization_id; /**< Implementation vendor or 327 organization ID. */ 328 mtapi_uint_t implementation_version; /**< The three last (rightmost) hex 329 digits are the minor number, and 330 those left of the minor number are 331 the major number.*/ 332 mtapi_uint_t number_of_domains; /**< Number of domains allowed by the 333 implementation.*/ 334 mtapi_uint_t number_of_nodes; /**< Number of nodes allowed by the 335 implementation.*/ 336 mtapi_uint_t hardware_concurrency; /**< Number of CPU cores available. */ 337 mtapi_uint_t used_memory; /**< Bytes of memory used by MTAPI. */ 338 }; 339 340 /** 341 * Info type. 342 * \memberof mtapi_info_struct 343 */ 344 typedef struct mtapi_info_struct mtapi_info_t; 345 346 /** 347 * Core affinity type. 348 * \ingroup CORE_AFFINITY_MASKS 349 */ 350 typedef mtapi_uint64_t mtapi_affinity_t; 351 352 353 /* ---- BASIC enumerations ------------------------------------------------- */ 354 355 /** 356 * Status codes returned in the status parameter of the MTAPI interface 357 * functions. 358 */ 359 enum mtapi_status_enum { 360 /* generic */ 361 MTAPI_SUCCESS, /**< success, no error */ 362 MTAPI_TIMEOUT, /**< timeout was reached */ 363 MTAPI_ERR_PARAMETER, /**< invalid parameter */ 364 MTAPI_ERR_ATTR_READONLY, /**< tried to write a read-only 365 attribute */ 366 MTAPI_ERR_ATTR_NUM, /**< invalid attribute number */ 367 MTAPI_ERR_ATTR_SIZE, /**< invalid attribute size */ 368 369 /* node specific */ 370 MTAPI_ERR_NODE_INITFAILED, /**< general error in node 371 initialization */ 372 MTAPI_ERR_NODE_INITIALIZED, /**< \a mtapi_initialize called for a 373 node that already had been 374 initialized */ 375 MTAPI_ERR_NODE_INVALID, /**< The node id is not valid */ 376 MTAPI_ERR_DOMAIN_INVALID, /**< the domain id is not valid */ 377 MTAPI_ERR_NODE_NOTINIT, /**< the node is not initialized */ 378 379 /* action specific */ 380 MTAPI_ERR_ACTION_INVALID, /**< The action id is not a valid action 381 id, i.e., no action was crated for 382 that ID or the action has been 383 deleted. */ 384 MTAPI_ERR_ACTION_EXISTS, /**< mtapi_action_create called with an 385 ID of an action that already had 386 been created */ 387 MTAPI_ERR_ACTION_LIMIT, /**< exceeded maximum number of actions 388 allowed */ 389 MTAPI_ERR_ACTION_NUM_INVALID, /**< The number of actions passed to 390 mtapi_task_start or 391 mtapi_queue_create is lower than 392 1. */ 393 MTAPI_ERR_ACTION_FAILED, /**< status that can be passed to the 394 runtime by 395 \a mtapi_context_status_set if the 396 task could not be completed as 397 intended */ 398 MTAPI_ERR_ACTION_CANCELLED, /**< status that can be passed to the 399 runtime by 400 \a mtapi_context_status_set if the 401 task execution is canceled */ 402 MTAPI_ERR_ACTION_DELETED, /**< All actions associated with the 403 task have been deleted before the 404 execution of the task was started 405 or the error code has been set in 406 the action code to 407 MTAPI_ERR_ACTION_DELETED by 408 \a mtapi_action_result_set. */ 409 MTAPI_ERR_ACTION_DISABLED, /**< All actions associated with the 410 task have been disabled before the 411 execution of the task was started 412 or the error code has been 413 set in the action code to 414 MTAPI_ERR_ACTION_DISABLED by 415 \a mtapi_action_result_set. */ 416 417 /* context specific */ 418 MTAPI_ERR_CONTEXT_INVALID, /**< returned if the context found is 419 in an invalid state */ 420 MTAPI_ERR_CONTEXT_OUTOFCONTEXT, /**< returned if action code is not 421 called in the context of a task 422 execution. This function must be 423 used in an action function only. 424 The action function must be called 425 from the MTAPI runtime system */ 426 427 /* task specific */ 428 MTAPI_ERR_TASK_INVALID, /**< invalid task handle encountered */ 429 MTAPI_ERR_TASK_LIMIT, /**< exceeded maximum number of tasks 430 allowed */ 431 432 /* job specific */ 433 MTAPI_ERR_JOB_INVALID, /**< invalid job handle or job ID */ 434 435 /* queue specific */ 436 MTAPI_ERR_QUEUE_INVALID, /**< argument is not a valid queue 437 handle or ID */ 438 MTAPI_ERR_QUEUE_DELETED, /**< a deleted queue is passed as an 439 argument */ 440 MTAPI_ERR_QUEUE_DISABLED, /**< a disable queue is passed as an 441 argument */ 442 MTAPI_ERR_QUEUE_LIMIT, /**< exceeded maximum number of queues 443 allowed */ 444 445 /* group specific */ 446 MTAPI_ERR_GROUP_INVALID, /**< invalid group handle encountered */ 447 MTAPI_ERR_GROUP_LIMIT, /**< exceeded maximum number of groups 448 allowed */ 449 MTAPI_GROUP_COMPLETED, /**< group completed, i.e., there are no 450 more tasks to wait for in the group 451 when waiting with 452 \a mtapi_group_wait_any */ 453 454 /* others */ 455 MTAPI_ERR_UNKNOWN, /**< unknown error */ 456 MTAPI_ERR_BUFFER_SIZE, /**< buffer size mismatch */ 457 MTAPI_ERR_RESULT_SIZE, /**< result buffer size mismatch 458 (e.g., in \a mtapi_task_wait) */ 459 MTAPI_ERR_ARG_SIZE, /**< invalid argument size */ 460 MTAPI_ERR_WAIT_PENDING, /**< mtapi_*_wait called twice on a 461 group or task which has not 462 finished */ 463 464 /* unsupported functions */ 465 MTAPI_ERR_FUNC_NOT_IMPLEMENTED, /**< The MTAPI function called is not 466 implemented by the runtime 467 system. */ 468 MTAPI_ERR_ARG_NOT_IMPLEMENTED, /**< The MTAPI function called is 469 implemented by the runtime, but it 470 does not support the arguments 471 passed. */ 472 473 /* features that may be not supported by some implementations */ 474 MTAPI_ERR_RUNTIME_REMOTETASKS_NOTSUPPORTED, 475 /**< The Runtime system does not support 476 remote tasks. This allows lighter 477 implementations for shared memory 478 environments. */ 479 MTAPI_ERR_RUNTIME_LOADBALANCING_NOTSUPPORTED, 480 /**< This error is returned when more 481 than one action is passed to 482 mtapi_task_start or 483 mtapi_queue_create and if the 484 runtime system does not implement 485 load balancing between nodes. This 486 allows light MTAPI implementation 487 for systems not having the 488 requirement for inter-node 489 load-balancing */ 490 491 /* core affinity specific */ 492 MTAPI_ERR_CORE_NUM, /**< This error occurs when trying to 493 set an affinity to a non-existing 494 core */ 495 }; 496 typedef enum mtapi_status_enum mtapi_status_t; 497 /**< defines the MTAPI state codes */ 498 499 500 /** 501 * Task states. 502 */ 503 enum mtapi_task_state_enum { 504 MTAPI_TASK_INTENTIONALLY_UNUSED, /**< never used */ 505 MTAPI_TASK_ERROR, /**< indicates internal error */ 506 MTAPI_TASK_PRENATAL, /**< initialization value for newly 507 allocated task descriptor */ 508 MTAPI_TASK_CREATED, /**< task is fully initialized */ 509 MTAPI_TASK_SCHEDULED, /**< task was scheduled */ 510 MTAPI_TASK_RUNNING, /**< task is running */ 511 MTAPI_TASK_WAITING, /**< task is being waited for */ 512 MTAPI_TASK_RETAINED, /**< task was started via a queue and 513 is retained */ 514 MTAPI_TASK_DELETED, /**< task was deleted */ 515 MTAPI_TASK_CANCELLED, /**< \a MTAPI_TASK_CANCELLED is the only 516 value specified by the MTAPI 517 specification, the others are 518 implementation specific and can be 519 used for debugging purposes. */ 520 MTAPI_TASK_COMPLETED /**< task completed execution 521 successfully */ 522 }; 523 typedef enum mtapi_task_state_enum mtapi_task_state_t; 524 /**< internal task state */ 525 526 /** 527 * Notification types for the runtime. 528 */ 529 enum mtapi_notification_enum { 530 MTAPI_NOTIF_PREFETCH, /**< implementation specific example */ 531 MTAPI_NOTIF_EXECUTE_NEXT /**< implementation specific example */ 532 }; 533 typedef enum mtapi_notification_enum mtapi_notification_t; 534 /**< runtime notification */ 535 536 /** 537 * Enum to select default or specific worker for priority setter 538 */ 539 enum mtapi_worker_priority_type_enum { 540 MTAPI_WORKER_PRIORITY_END = 0, 541 MTAPI_WORKER_PRIORITY_DEFAULT = 1, 542 MTAPI_WORKER_PRIORITY_WORKER = 100, 543 MTAPI_WORKER_PRIORITY_WORKER_0 = MTAPI_WORKER_PRIORITY_WORKER + 0, 544 MTAPI_WORKER_PRIORITY_WORKER_1 = MTAPI_WORKER_PRIORITY_WORKER + 1, 545 MTAPI_WORKER_PRIORITY_WORKER_2 = MTAPI_WORKER_PRIORITY_WORKER + 2, 546 MTAPI_WORKER_PRIORITY_WORKER_3 = MTAPI_WORKER_PRIORITY_WORKER + 3, 547 MTAPI_WORKER_PRIORITY_WORKER_4 = MTAPI_WORKER_PRIORITY_WORKER + 4, 548 MTAPI_WORKER_PRIORITY_WORKER_5 = MTAPI_WORKER_PRIORITY_WORKER + 5, 549 MTAPI_WORKER_PRIORITY_WORKER_6 = MTAPI_WORKER_PRIORITY_WORKER + 6, 550 MTAPI_WORKER_PRIORITY_WORKER_7 = MTAPI_WORKER_PRIORITY_WORKER + 7, 551 MTAPI_WORKER_PRIORITY_WORKER_8 = MTAPI_WORKER_PRIORITY_WORKER + 8, 552 MTAPI_WORKER_PRIORITY_WORKER_9 = MTAPI_WORKER_PRIORITY_WORKER + 9, 553 MTAPI_WORKER_PRIORITY_WORKER_10 = MTAPI_WORKER_PRIORITY_WORKER + 10, 554 MTAPI_WORKER_PRIORITY_WORKER_11 = MTAPI_WORKER_PRIORITY_WORKER + 11, 555 MTAPI_WORKER_PRIORITY_WORKER_12 = MTAPI_WORKER_PRIORITY_WORKER + 12, 556 MTAPI_WORKER_PRIORITY_WORKER_13 = MTAPI_WORKER_PRIORITY_WORKER + 13, 557 MTAPI_WORKER_PRIORITY_WORKER_14 = MTAPI_WORKER_PRIORITY_WORKER + 14, 558 MTAPI_WORKER_PRIORITY_WORKER_15 = MTAPI_WORKER_PRIORITY_WORKER + 15, 559 MTAPI_WORKER_PRIORITY_WORKER_16 = MTAPI_WORKER_PRIORITY_WORKER + 16, 560 MTAPI_WORKER_PRIORITY_WORKER_17 = MTAPI_WORKER_PRIORITY_WORKER + 17, 561 MTAPI_WORKER_PRIORITY_WORKER_18 = MTAPI_WORKER_PRIORITY_WORKER + 18, 562 MTAPI_WORKER_PRIORITY_WORKER_19 = MTAPI_WORKER_PRIORITY_WORKER + 19, 563 MTAPI_WORKER_PRIORITY_WORKER_20 = MTAPI_WORKER_PRIORITY_WORKER + 20, 564 MTAPI_WORKER_PRIORITY_WORKER_21 = MTAPI_WORKER_PRIORITY_WORKER + 21, 565 MTAPI_WORKER_PRIORITY_WORKER_22 = MTAPI_WORKER_PRIORITY_WORKER + 22, 566 MTAPI_WORKER_PRIORITY_WORKER_23 = MTAPI_WORKER_PRIORITY_WORKER + 23, 567 MTAPI_WORKER_PRIORITY_WORKER_24 = MTAPI_WORKER_PRIORITY_WORKER + 24, 568 MTAPI_WORKER_PRIORITY_WORKER_25 = MTAPI_WORKER_PRIORITY_WORKER + 25, 569 MTAPI_WORKER_PRIORITY_WORKER_26 = MTAPI_WORKER_PRIORITY_WORKER + 26, 570 MTAPI_WORKER_PRIORITY_WORKER_27 = MTAPI_WORKER_PRIORITY_WORKER + 27, 571 MTAPI_WORKER_PRIORITY_WORKER_28 = MTAPI_WORKER_PRIORITY_WORKER + 28, 572 MTAPI_WORKER_PRIORITY_WORKER_29 = MTAPI_WORKER_PRIORITY_WORKER + 29, 573 MTAPI_WORKER_PRIORITY_WORKER_30 = MTAPI_WORKER_PRIORITY_WORKER + 30, 574 MTAPI_WORKER_PRIORITY_WORKER_31 = MTAPI_WORKER_PRIORITY_WORKER + 31, 575 MTAPI_WORKER_PRIORITY_WORKER_32 = MTAPI_WORKER_PRIORITY_WORKER + 32, 576 MTAPI_WORKER_PRIORITY_WORKER_33 = MTAPI_WORKER_PRIORITY_WORKER + 33, 577 MTAPI_WORKER_PRIORITY_WORKER_34 = MTAPI_WORKER_PRIORITY_WORKER + 34, 578 MTAPI_WORKER_PRIORITY_WORKER_35 = MTAPI_WORKER_PRIORITY_WORKER + 35, 579 MTAPI_WORKER_PRIORITY_WORKER_36 = MTAPI_WORKER_PRIORITY_WORKER + 36, 580 MTAPI_WORKER_PRIORITY_WORKER_37 = MTAPI_WORKER_PRIORITY_WORKER + 37, 581 MTAPI_WORKER_PRIORITY_WORKER_38 = MTAPI_WORKER_PRIORITY_WORKER + 38, 582 MTAPI_WORKER_PRIORITY_WORKER_39 = MTAPI_WORKER_PRIORITY_WORKER + 39, 583 MTAPI_WORKER_PRIORITY_WORKER_40 = MTAPI_WORKER_PRIORITY_WORKER + 40, 584 MTAPI_WORKER_PRIORITY_WORKER_41 = MTAPI_WORKER_PRIORITY_WORKER + 41, 585 MTAPI_WORKER_PRIORITY_WORKER_42 = MTAPI_WORKER_PRIORITY_WORKER + 42, 586 MTAPI_WORKER_PRIORITY_WORKER_43 = MTAPI_WORKER_PRIORITY_WORKER + 43, 587 MTAPI_WORKER_PRIORITY_WORKER_44 = MTAPI_WORKER_PRIORITY_WORKER + 44, 588 MTAPI_WORKER_PRIORITY_WORKER_45 = MTAPI_WORKER_PRIORITY_WORKER + 45, 589 MTAPI_WORKER_PRIORITY_WORKER_46 = MTAPI_WORKER_PRIORITY_WORKER + 46, 590 MTAPI_WORKER_PRIORITY_WORKER_47 = MTAPI_WORKER_PRIORITY_WORKER + 47, 591 MTAPI_WORKER_PRIORITY_WORKER_48 = MTAPI_WORKER_PRIORITY_WORKER + 48, 592 MTAPI_WORKER_PRIORITY_WORKER_49 = MTAPI_WORKER_PRIORITY_WORKER + 49, 593 MTAPI_WORKER_PRIORITY_WORKER_50 = MTAPI_WORKER_PRIORITY_WORKER + 50, 594 MTAPI_WORKER_PRIORITY_WORKER_51 = MTAPI_WORKER_PRIORITY_WORKER + 51, 595 MTAPI_WORKER_PRIORITY_WORKER_52 = MTAPI_WORKER_PRIORITY_WORKER + 52, 596 MTAPI_WORKER_PRIORITY_WORKER_53 = MTAPI_WORKER_PRIORITY_WORKER + 53, 597 MTAPI_WORKER_PRIORITY_WORKER_54 = MTAPI_WORKER_PRIORITY_WORKER + 54, 598 MTAPI_WORKER_PRIORITY_WORKER_55 = MTAPI_WORKER_PRIORITY_WORKER + 55, 599 MTAPI_WORKER_PRIORITY_WORKER_56 = MTAPI_WORKER_PRIORITY_WORKER + 56, 600 MTAPI_WORKER_PRIORITY_WORKER_57 = MTAPI_WORKER_PRIORITY_WORKER + 57, 601 MTAPI_WORKER_PRIORITY_WORKER_58 = MTAPI_WORKER_PRIORITY_WORKER + 58, 602 MTAPI_WORKER_PRIORITY_WORKER_59 = MTAPI_WORKER_PRIORITY_WORKER + 59, 603 MTAPI_WORKER_PRIORITY_WORKER_60 = MTAPI_WORKER_PRIORITY_WORKER + 60, 604 MTAPI_WORKER_PRIORITY_WORKER_61 = MTAPI_WORKER_PRIORITY_WORKER + 61, 605 MTAPI_WORKER_PRIORITY_WORKER_62 = MTAPI_WORKER_PRIORITY_WORKER + 62, 606 MTAPI_WORKER_PRIORITY_WORKER_63 = MTAPI_WORKER_PRIORITY_WORKER + 63 607 }; 608 /** 609 * Enum to select default or specific worker for priority setter 610 */ 611 typedef enum mtapi_worker_priority_type_enum mtapi_worker_priority_type_t; 612 613 /** 614 * Describes the default priority of all workers or the priority of a 615 * specific worker. 616 */ 617 struct mtapi_worker_priority_entry_struct { 618 mtapi_worker_priority_type_t type; /**< default or specific worker */ 619 embb_thread_priority_t priority; /**< priority to set */ 620 }; 621 /** 622 * Describes the default priority of all workers or the priority of a 623 * specific worker. 624 */ 625 typedef struct mtapi_worker_priority_entry_struct mtapi_worker_priority_entry_t; 626 627 /** 628 * Node attributes, to be extended for implementation specific attributes 629 */ 630 enum mtapi_node_attributes_enum { 631 MTAPI_NODE_CORE_AFFINITY, /**< use the given cores only */ 632 MTAPI_NODE_NUMCORES, /**< number of cores provided by the 633 node */ 634 MTAPI_NODE_TYPE, /**< the nodes type, SMP or DSP */ 635 MTAPI_NODE_MAX_TASKS, /**< maximum number of tasks allowed by 636 the node */ 637 MTAPI_NODE_MAX_ACTIONS, /**< maximum number of actions allowed 638 by the node */ 639 MTAPI_NODE_MAX_GROUPS, /**< maximum number of groups allowed 640 by the node */ 641 MTAPI_NODE_MAX_QUEUES, /**< maximum number of queues allowed 642 by the node */ 643 MTAPI_NODE_QUEUE_LIMIT, /**< maximum number of elements that fit 644 into a queue */ 645 MTAPI_NODE_MAX_JOBS, /**< maximum number of jobs allowed by 646 the node */ 647 MTAPI_NODE_MAX_ACTIONS_PER_JOB, /**< maximum number of actions in a job 648 allowed by the node */ 649 MTAPI_NODE_MAX_PRIORITIES, /**< maximum number of priorities 650 allowed by the node */ 651 MTAPI_NODE_REUSE_MAIN_THREAD, /**< reuse main thread as worker */ 652 MTAPI_NODE_WORKER_PRIORITIES /**< set worker priorites */ 653 }; 654 /** size of the \a MTAPI_NODE_CORE_AFFINITY attribute */ 655 #define MTAPI_NODE_CORE_AFFINITY_SIZE sizeof(embb_core_set_t) 656 /** size of the \a MTAPI_NODES_NUMCORES attribute */ 657 #define MTAPI_NODE_NUMCORES_SIZE sizeof(mtapi_uint_t) 658 /** size of the \a MTAPI_NODE_TYPE attribute */ 659 #define MTAPI_NODE_TYPE_SIZE sizeof(mtapi_uint_t) 660 /** size of the \a MTAPI_NODE_MAX_TASKS attribute */ 661 #define MTAPI_NODE_MAX_TASKS_SIZE sizeof(mtapi_uint_t) 662 /** size of the \a MTAPI_NODE_MAX_ACTIONS attribute */ 663 #define MTAPI_NODE_MAX_ACTIONS_SIZE sizeof(mtapi_uint_t) 664 /** size of the \a MTAPI_NODE_MAX_GROUPS attribute */ 665 #define MTAPI_NODE_MAX_GROUPS_SIZE sizeof(mtapi_uint_t) 666 /** size of the \a MTAPI_NODE_MAX_QUEUES attribute */ 667 #define MTAPI_NODE_MAX_QUEUES_SIZE sizeof(mtapi_uint_t) 668 /** size of the \a MTAPI_NODE_QUEUE_LIMIT attribute */ 669 #define MTAPI_NODE_QUEUE_LIMIT_SIZE sizeof(mtapi_uint_t) 670 /** size of the \a MTAPI_NODE_MAX_JOBS attribute */ 671 #define MTAPI_NODE_MAX_JOBS_SIZE sizeof(mtapi_uint_t) 672 /** size of the \a MTAPI_NODE_MAX_ACTIONS_PER_JOB attribute */ 673 #define MTAPI_NODE_MAX_ACTIONS_PER_JOB_SIZE sizeof(mtapi_uint_t) 674 /** size of the \a MTAPI_NODE_MAX_PRIORITIES attribute */ 675 #define MTAPI_NODE_MAX_PRIORITIES_SIZE sizeof(mtapi_uint_t) 676 /** size of the \a MTAPI_NODE_REUSE_MAIN_THREAD attribute */ 677 #define MTAPI_NODE_REUSE_MAIN_THREAD_SIZE sizeof(mtapi_boolean_t) 678 /** size of the \a MTAPI_NODE_WORKER_PRIORITIES attribute */ 679 #define MTAPI_NODE_WORKER_PRIORITIES_SIZE 0 680 681 /* example attribute value */ 682 #define MTAPI_NODE_TYPE_SMP 1 683 #define MTAPI_NODE_TYPE_DSP 2 684 685 /** 686 * Task handle type. 687 * \memberof mtapi_task_hndl_struct 688 */ 689 typedef struct mtapi_task_hndl_struct mtapi_task_hndl_t; 690 691 /** task completion callback */ 692 typedef void(*mtapi_task_complete_function_t)( 693 MTAPI_IN mtapi_task_hndl_t task, 694 MTAPI_OUT mtapi_status_t* status); 695 696 /** task attributes */ 697 enum mtapi_task_attributes_enum { 698 MTAPI_TASK_DETACHED, /**< task is detached, i.e., the runtime 699 system cared about deleting 700 internal data structures 701 representing the task; detached 702 tasks cannot be accessed via task 703 handles */ 704 MTAPI_TASK_INSTANCES, /**< indicates how many parallel 705 instances of task shall be started 706 by MTAPI; the default case is that 707 each task is executed exactly once, 708 setting this value to \a n, the 709 corresponding action code will be 710 executed n times, if possible in 711 parallel */ 712 MTAPI_TASK_PRIORITY, /**< the priority the task should be 713 run at */ 714 MTAPI_TASK_AFFINITY, /**< the affinity of the task */ 715 MTAPI_TASK_USER_DATA, /**< pointer to user data associated 716 with the task */ 717 MTAPI_TASK_COMPLETE_FUNCTION, /**< pointer to a function being called 718 when the task finishes execution */ 719 MTAPI_TASK_PROBLEM_SIZE /**< integer indicating the relative 720 problem size of the task */ 721 }; 722 /** size of the \a MTAPI_TASK_DETACHED attribute */ 723 #define MTAPI_TASK_DETACHED_SIZE sizeof(mtapi_boolean_t) 724 /** size of the \a MTAPI_TASK_INSTANCES attribute */ 725 #define MTAPI_TASK_INSTANCES_SIZE sizeof(mtapi_uint_t) 726 /** size of the \a MTAPI_TASK_PRIORITY attribute */ 727 #define MTAPI_TASK_PRIORITY_SIZE sizeof(mtapi_uint_t) 728 /** size of the \a MTAPI_TASK_AFFINITY attribute */ 729 #define MTAPI_TASK_AFFINITY_SIZE sizeof(mtapi_affinity_t) 730 /** size of the \a MTAPI_TASK_PROBLEM_SIZE attribute */ 731 #define MTAPI_TASK_PROBLEM_SIZE_SIZE sizeof(mtapi_uint_t) 732 733 734 /** 735 * action attributes 736 */ 737 enum mtapi_action_attributes_enum { 738 MTAPI_ACTION_GLOBAL, /**< indicates global visibility of the 739 action */ 740 MTAPI_ACTION_AFFINITY, /**< the affinity of tasks using the 741 action */ 742 MTAPI_ACTION_DOMAIN_SHARED /**< indicates domain wide visibility of 743 the action */ 744 }; 745 /** size of the \a MTAPI_ACTION_GLOBAL attribute */ 746 #define MTAPI_ACTION_GLOBAL_SIZE sizeof(mtapi_boolean_t) 747 /** size of the \a MTAPI_ACTION_AFFINITY attribute */ 748 #define MTAPI_ACTION_AFFINITY_SIZE sizeof(mtapi_affinity_t) 749 /** size of the \a MTAPI_ACTION_DOMAIN_SHARED attribute */ 750 #define MTAPI_ACTION_DOMAIN_SHARED_SIZE sizeof(mtapi_boolean_t) 751 752 753 /** 754 * queue attributes 755 */ 756 enum mtapi_queue_attributes_enum { 757 MTAPI_QUEUE_GLOBAL, /**< indicates global visibility of the 758 queue */ 759 MTAPI_QUEUE_PRIORITY, /**< the priority of tasks launched via 760 the queue */ 761 MTAPI_QUEUE_LIMIT, /**< maximum tasks in the queue */ 762 MTAPI_QUEUE_ORDERED, /**< toggles ordered execution of tasks 763 in the queue */ 764 MTAPI_QUEUE_RETAIN, /**< indicates whether tasks should be 765 retained if the queue is disabled */ 766 MTAPI_QUEUE_DOMAIN_SHARED /**< indicates domain wide visibility of 767 the action */ 768 }; 769 /** size of the \a MTAPI_QUEUE_GLOBAL attribute */ 770 #define MTAPI_QUEUE_GLOBAL_SIZE sizeof(mtapi_boolean_t) 771 /** size of the \a MTAPI_QUEUE_PRIORITY attribute */ 772 #define MTAPI_QUEUE_PRIORITY_SIZE sizeof(mtapi_uint_t) 773 /** size of the \a MTAPI_QUEUE_LIMIT attribute */ 774 #define MTAPI_QUEUE_LIMIT_SIZE sizeof(mtapi_uint_t) 775 /** size of the \a MTAPI_QUEUE_ORDERED attribute */ 776 #define MTAPI_QUEUE_ORDERED_SIZE sizeof(mtapi_boolean_t) 777 /** size of the \a MTAPI_QUEUE_RETAIN attribute */ 778 #define MTAPI_QUEUE_RETAIN_SIZE sizeof(mtapi_boolean_t) 779 /** size of the \a MTAPI_QUEUE_DOMAIN_SHARED attribute */ 780 #define MTAPI_QUEUE_DOMAIN_SHARED_SIZE sizeof(mtapi_boolean_t) 781 782 783 #define MTAPI_ATTRIBUTE_VALUE(value) ((void*)(value)) 784 #define MTAPI_ATTRIBUTE_POINTER_AS_VALUE 0 785 786 787 /* ---- ATTRIBUTES --------------------------------------------------------- */ 788 789 /** 790 * Node attributes. 791 * \ingroup RUNTIME_INIT_SHUTDOWN 792 */ 793 struct mtapi_node_attributes_struct { 794 embb_core_set_t core_affinity; /**< stores MTAPI_NODE_CORE_AFFINITY */ 795 mtapi_uint_t num_cores; /**< stores MTAPI_NODE_NUMCORES */ 796 mtapi_uint_t type; /**< stores MTAPI_NODE_TYPE */ 797 mtapi_uint_t max_tasks; /**< stores MTAPI_NODE_MAX_TASKS */ 798 mtapi_uint_t max_actions; /**< stores MTAPI_NODE_MAX_ACTIONS */ 799 mtapi_uint_t max_groups; /**< stores MTAPI_NODE_MAX_GROUPS */ 800 mtapi_uint_t max_queues; /**< stores MTAPI_NODE_MAX_QUEUES */ 801 mtapi_uint_t queue_limit; /**< stores MTAPI_NODE_QUEUE_LIMIT */ 802 mtapi_uint_t max_jobs; /**< stores MTAPI_NODE_MAX_JOBS */ 803 mtapi_uint_t max_actions_per_job; /**< stores 804 MTAPI_NODE_MAX_ACTIONS_PER_JOB */ 805 mtapi_uint_t max_priorities; /**< stores MTAPI_NODE_MAX_PRIORITIES */ 806 mtapi_boolean_t reuse_main_thread; /**< stores 807 MTAPI_NODE_REUSE_MAIN_THREAD */ 808 mtapi_worker_priority_entry_t * worker_priorities; 809 /**< stores 810 MTAPI_NODE_WORKER_PRIORITIES */ 811 }; 812 813 /** 814 * Action attributes. 815 * \ingroup ACTIONS 816 */ 817 struct mtapi_action_attributes_struct { 818 mtapi_boolean_t global; /**< stores MTAPI_ACTION_GLOBAL */ 819 mtapi_affinity_t affinity; /**< stores MTAPI_ACTION_AFFINITY */ 820 mtapi_boolean_t domain_shared; /**< stores MTAPI_ACTION_DOMAIN_SHARED*/ 821 }; 822 823 /** 824 * Task attributes. 825 * \ingroup TASKS 826 */ 827 struct mtapi_task_attributes_struct { 828 mtapi_boolean_t is_detached; /**< stores MTAPI_TASK_DETACHED */ 829 mtapi_uint_t num_instances; /**< stores MTAPI_TASK_INSTANCES */ 830 mtapi_uint_t priority; /**< stores MTAPI_TASK_PRIORITY */ 831 mtapi_affinity_t affinity; /**< stores MTAPI_TASK_AFFINITY */ 832 void * user_data; /**< stores MTAPI_TASK_USER_DATA */ 833 mtapi_task_complete_function_t 834 complete_func; /**< stores 835 MTAPI_TASK_COMPLETE_FUNCTION */ 836 mtapi_uint_t problem_size; /**< stores MTAPI_TASK_PROBLEM_SIZE */ 837 }; 838 839 /** 840 * Queue attributes. 841 * \ingroup QUEUES 842 */ 843 struct mtapi_queue_attributes_struct { 844 mtapi_boolean_t global; /**< stores MTAPI_QUEUE_GLOBAL */ 845 mtapi_uint_t priority; /**< stores MTAPI_QUEUE_PRIORITY */ 846 mtapi_uint_t limit; /**< stores MTAPI_QUEUE_LIMIT */ 847 mtapi_boolean_t ordered; /**< stores MTAPI_QUEUE_ORDERED */ 848 mtapi_boolean_t retain; /**< stores MTAPI_QUEUE_RETAIN */ 849 mtapi_boolean_t domain_shared; /**< stores MTAPI_QUEUE_DOMAIN_SHARED */ 850 }; 851 852 /** 853 * Group attributes. 854 * \ingroup TASK_GROUPS 855 */ 856 struct mtapi_group_attributes_struct { 857 mtapi_int_t some_value; /**< just a placeholder */ 858 }; 859 860 /** 861 * Node attributes type. 862 * \memberof mtapi_node_attributes_struct 863 */ 864 typedef struct mtapi_node_attributes_struct mtapi_node_attributes_t; 865 866 /** 867 * Action attributes type. 868 * \memberof mtapi_action_attributes_struct 869 */ 870 typedef struct mtapi_action_attributes_struct mtapi_action_attributes_t; 871 872 /** 873 * Task attributes type. 874 * \memberof mtapi_task_attributes_struct 875 */ 876 typedef struct mtapi_task_attributes_struct mtapi_task_attributes_t; 877 878 /** 879 * Queue attributes type. 880 * \memberof mtapi_queue_attributes_struct 881 */ 882 typedef struct mtapi_queue_attributes_struct mtapi_queue_attributes_t; 883 884 /** 885 * Group attributes type. 886 * \memberof mtapi_group_attributes_struct 887 */ 888 typedef struct mtapi_group_attributes_struct mtapi_group_attributes_t; 889 890 /** short form for using the default node attributes */ 891 #define MTAPI_DEFAULT_NODE_ATTRIBUTES MTAPI_NULL 892 893 /** short form for using the default action attributes */ 894 #define MTAPI_DEFAULT_ACTION_ATTRIBUTES MTAPI_NULL 895 896 /** short form for using the default task attributes */ 897 #define MTAPI_DEFAULT_TASK_ATTRIBUTES MTAPI_NULL 898 899 /** short form for using the default queue attributes */ 900 #define MTAPI_DEFAULT_QUEUE_ATTRIBUTES MTAPI_NULL 901 902 /** short form for using the default group attributes */ 903 #define MTAPI_DEFAULT_GROUP_ATTRIBUTES MTAPI_NULL 904 905 906 /* ---- FUNCTION TYPES ----------------------------------------------------- */ 907 908 /** 909 * Task context type. 910 * \memberof embb_mtapi_task_context_struct 911 */ 912 typedef struct embb_mtapi_task_context_struct mtapi_task_context_t; 913 914 /** 915 * An action function is the executable software function that implements an 916 * action. 917 * 918 * The runtime passes arguments to the action function when a task is started. 919 * Passing arguments from one node to another node should be implemented as a 920 * copy operation. Just as the arguments are passed before start of execution, 921 * the result buffer is copied back to the calling node after the action 922 * function terminates. In shared memory environments, the copying of data in 923 * both cases is not necessary. The node-local data is data used by several 924 * action functions being executed on the same node (or at least in the same 925 * address space). The shared data is specified when the action is created. 926 * 927 * An action function can interact with the runtime environment through a task 928 * context object of type mtapi_task_context_t . A task context object is 929 * allocated and managed by the runtime. The runtime passes a pointer to the 930 * context object when the action function is invoked. The action may then 931 * query information about the execution context (e.g., its core number, the 932 * number of tasks and task number in a multi-instance task, polling the task 933 * state) by calling the mtapi_context_* functions. Furthermore it is possible 934 * to pass information from the action function to the runtime system which 935 * is executing the action function (setting the status manually, for example). 936 * All of these mtapi_context_* functions are called in the context of task 937 * execution. 938 * 939 * \ingroup ACTION_FUNCTIONS 940 */ 941 typedef void(*mtapi_action_function_t)( 942 const void* args, /**< arguments */ 943 mtapi_size_t args_size, /**< length of arguments */ 944 void* result_buffer, /**< buffer for storing results */ 945 mtapi_size_t result_buffer_size, /**< length of result_buffer */ 946 const void* node_local_data, /**< node-local data, shared data by 947 several tasks executed on the same 948 node */ 949 mtapi_size_t node_local_data_size, /**< length of shared data */ 950 mtapi_task_context_t * context /**< MTAPI task context provided by the 951 runtime systems identifying the 952 current task for calling back the 953 runtime system from the action 954 function */ 955 ); 956 957 958 /* ---- HANDLES and IDs ---------------------------------------------------- */ 959 960 typedef mtapi_uint_t mtapi_action_id_t; 961 typedef mtapi_uint_t mtapi_job_id_t; 962 typedef mtapi_uint_t mtapi_queue_id_t; 963 typedef mtapi_uint_t mtapi_group_id_t; 964 typedef mtapi_uint_t mtapi_task_id_t; 965 966 /** 967 * Action handle. 968 * \ingroup ACTIONS 969 */ 970 struct mtapi_action_hndl_struct { 971 mtapi_uint_t tag; /**< version of this handle */ 972 mtapi_action_id_t id; /**< pool index of this handle */ 973 }; 974 975 /** 976 * Action handle type. 977 * \memberof mtapi_action_hndl_struct 978 */ 979 typedef struct mtapi_action_hndl_struct mtapi_action_hndl_t; 980 981 /** 982 * Job handle. 983 * \ingroup JOBS 984 */ 985 struct mtapi_job_hndl_struct { 986 mtapi_uint_t tag; /**< version of this handle */ 987 mtapi_job_id_t id; /**< pool index of this handle */ 988 }; 989 990 /** 991 * Job handle type. 992 * \memberof mtapi_job_hndl_struct 993 */ 994 typedef struct mtapi_job_hndl_struct mtapi_job_hndl_t; 995 996 /** 997 * Queue handle. 998 * \ingroup QUEUES 999 */ 1000 struct mtapi_queue_hndl_struct { 1001 mtapi_uint_t tag; /**< version of this handle */ 1002 mtapi_queue_id_t id; /**< pool index of this handle */ 1003 }; 1004 1005 /** 1006 * Queue handle type. 1007 * \memberof mtapi_queue_hndl_struct 1008 */ 1009 typedef struct mtapi_queue_hndl_struct mtapi_queue_hndl_t; 1010 1011 /** 1012 * Group handle. 1013 * \ingroup TASK_GROUPS 1014 */ 1015 struct mtapi_group_hndl_struct { 1016 mtapi_uint_t tag; /**< version of this handle */ 1017 mtapi_group_id_t id; /**< pool index of this handle */ 1018 }; 1019 1020 /** 1021 * Group handle type. 1022 * \memberof mtapi_group_hndl_struct 1023 */ 1024 typedef struct mtapi_group_hndl_struct mtapi_group_hndl_t; 1025 1026 /** 1027 * Task handle. 1028 * \ingroup TASKS 1029 */ 1030 struct mtapi_task_hndl_struct { 1031 mtapi_uint_t tag; /**< version of this handle */ 1032 mtapi_task_id_t id; /**< pool index of this handle */ 1033 }; 1034 1035 // was forward declared 1036 //typedef struct mtapi_task_hndl_struct mtapi_task_hndl_t; 1037 1038 1039 /* ---- BASIC CONSTANTS ---------------------------------------------------- */ 1040 1041 #define MTAPI_TRUE ((mtapi_boolean_t)1) 1042 #define MTAPI_FALSE ((mtapi_boolean_t)0) 1043 1044 extern mtapi_group_hndl_t MTAPI_GROUP_NONE; 1045 1046 #define MTAPI_NULL 0 1047 1048 #define TEN_SECONDS 10000 1049 #define MTAPI_INFINITE -1 1050 #define MTAPI_NOWAIT 0 1051 1052 #define MTAPI_NODE_MAX_TASKS_DEFAULT 1024 1053 #define MTAPI_NODE_MAX_ACTIONS_DEFAULT 1024 1054 #define MTAPI_NODE_MAX_GROUPS_DEFAULT 128 1055 #define MTAPI_NODE_MAX_QUEUES_DEFAULT 16 1056 /** default size for MTAPI queues */ 1057 #define MTAPI_NODE_QUEUE_LIMIT_DEFAULT 1024 1058 #define MTAPI_NODE_MAX_JOBS_DEFAULT 256 1059 #define MTAPI_NODE_MAX_ACTIONS_PER_JOB_DEFAULT 4 1060 #define MTAPI_NODE_MAX_PRIORITIES_DEFAULT 4 1061 1062 #define MTAPI_JOB_ID_INVALID 0 1063 #define MTAPI_DOMAIN_ID_INVALID 0 1064 #define MTAPI_NODE_ID_INVALID 0 1065 1066 #define MTAPI_TASK_ID_NONE 0 1067 #define MTAPI_GROUP_ID_NONE 0 1068 #define MTAPI_QUEUE_ID_NONE 0 1069 #define MTAPI_ACTION_ID_NONE 0 1070 1071 1072 /* ---- RUNTIME INIT & SHUTDOWN -------------------------------------------- */ 1073 1074 /** 1075 * \defgroup RUNTIME_INIT_SHUTDOWN General 1076 * 1077 * \ingroup C_MTAPI 1078 * 1079 * Initialization, introspection, and finalization functions. 1080 * 1081 * All applications wishing to use MTAPI functionality must use the 1082 * initialization and finalization routines. After initialization, the 1083 * introspection functions can provide important information to MTAPI-based 1084 * applications. 1085 */ 1086 1087 /** 1088 * This function initializes a node attributes object. 1089 * 1090 * A node attributes object is a container of node attributes. It is an 1091 * optional argument passed to mtapi_initialize() to specify non-default node 1092 * attributes when creating a node. 1093 * 1094 * To set node attributes to non-default values, the application must allocate 1095 * a node attributes object of type mtapi_node_attributes_t and initialize it 1096 * with a call to mtapi_nodeattr_init(). The application may call 1097 * mtapi_nodeattr_set() to specify attribute values. Calls to 1098 * mtapi_nodeattr_init() have no effect on node attributes after the node has 1099 * been created and initialized with mtapi_initialize(). The 1100 * mtapi_node_attributes_t object may safely be deleted by the application 1101 * after the call to mtapi_nodeattr_init(). 1102 * 1103 * On success, \c *status is set to \c MTAPI_SUCCESS. On error, \c *status is 1104 * set to the appropriate error defined below. 1105 * Error code | Description 1106 * ---------------------- | --------------------------------------------------- 1107 * \c MTAPI_ERR_PARAMETER | Invalid attributes parameter. 1108 * 1109 * \see mtapi_initialize(), mtapi_nodeattr_set() 1110 * 1111 * \notthreadsafe 1112 * \memberof mtapi_node_attributes_struct 1113 */ 1114 void mtapi_nodeattr_init( 1115 MTAPI_OUT mtapi_node_attributes_t* attributes, 1116 /**< [out] Pointer to attributes */ 1117 MTAPI_OUT mtapi_status_t* status /**< [out] Pointer to error code, 1118 may be \c MTAPI_NULL */ 1119 ); 1120 1121 /** 1122 * This function sets node attribute values in a node attributes object. 1123 * 1124 * A node attributes object is a container of node attributes, optionally 1125 * passed to mtapi_initialize() to specify non-default node attributes when 1126 * creating a node. 1127 * 1128 * \c attributes is a pointer to a node attributes object that was previously 1129 * initialized with a call to mtapi_nodeattr_init(). Calls to 1130 * mtapi_nodeattr_set() have no effect on node attributes after the node has 1131 * been created and initialized with mtapi_initialize(). The node attributes 1132 * object may safely be deleted by the application after the call to 1133 * mtapi_initialize(). 1134 * 1135 * See the table below for a list of predefined attribute numbers and the 1136 * sizes of the attribute values. The application must set \c attribute_size to 1137 * the exact size in bytes of the attribute value. 1138 * Additional attributes may be defined by the implementation. 1139 * 1140 * MTAPI-defined node attributes: 1141 * <table> 1142 * <tr> 1143 * <th>Attribute num</th> 1144 * <th>Description</th> 1145 * <th>Data Type</th> 1146 * <th>Default</th> 1147 * </tr> 1148 * <tr> 1149 * <td>\c MTAPI_NODES_NUMCORES</td> 1150 * <td>(Read-only) number of processor cores of the node.</td> 1151 * <td>\c mtapi_uint_t</td> 1152 * <td>(none)</td> 1153 * </tr> 1154 * </table> 1155 * 1156 * On success, \c *status is set to \c MTAPI_SUCCESS. On error, \c *status is 1157 * set to the appropriate error defined below. 1158 * Error code | Description 1159 * -------------------------- | ----------------------------------------------- 1160 * \c MTAPI_ERR_ATTR_READONLY | Attribute cannot be modified. 1161 * \c MTAPI_ERR_PARAMETER | Invalid attribute parameter. 1162 * \c MTAPI_ERR_ATTR_NUM | Unknown attribute number. 1163 * \c MTAPI_ERR_ATTR_SIZE | Incorrect attribute size. 1164 * 1165 * \see mtapi_nodeattr_init(), mtapi_initialize() 1166 * 1167 * \notthreadsafe 1168 * \memberof mtapi_node_attributes_struct 1169 */ 1170 void mtapi_nodeattr_set( 1171 MTAPI_INOUT mtapi_node_attributes_t* attributes, 1172 /**< [in, out] Pointer to attributes */ 1173 MTAPI_IN mtapi_uint_t attribute_num, /**< [in] Attribute id */ 1174 MTAPI_IN void* attribute, /**< [in] Pointer to attribute value */ 1175 MTAPI_IN mtapi_size_t attribute_size, 1176 /**< [in] Size of attribute value. may 1177 be 0, attribute is interpreted as 1178 value in that case */ 1179 MTAPI_OUT mtapi_status_t* status /**< [out] Pointer to error code, 1180 may be \c MTAPI_NULL */ 1181 ); 1182 1183 /** 1184 * Initializes the MTAPI environment on a given MTAPI node in a given MTAPI 1185 * domain. 1186 * 1187 * It must be called on each node using MTAPI. A node maps to a process, 1188 * thread, thread pool, instance of an operating system, hardware accelerator, 1189 * processor core, a cluster of processor cores, or another abstract processing 1190 * entity with an independent program counter. In other words, an MTAPI node 1191 * is an independent thread of control. 1192 * 1193 * Application software running on an MTAPI node must call mtapi_initialize() 1194 * once per node. It is an error to call mtapi_initialize() multiple times 1195 * from a given node, unless mtapi_finalize() is called in between. 1196 * 1197 * The values for \c domain_id and \c node_id must be known a priori by the 1198 * application and MTAPI. 1199 * 1200 * \c mtapi_info is used to obtain information from the MTAPI implementation, 1201 * including MTAPI and the underlying implementation version numbers, 1202 * implementation vendor identification, the number of cores of a node, and 1203 * vendor-specific implementation information. See the header files for 1204 * additional information. 1205 * 1206 * A given MTAPI implementation will specify what is a node, i.e., how the 1207 * concrete system is partitioned into nodes and what are the underlying units 1208 * of execution executing tasks, e.g., threads, a thread pool, processes, or 1209 * hardware units. 1210 * 1211 * \c attributes is a pointer to a node attributes object that was previously 1212 * prepared with mtapi_nodeattr_init() and mtapi_nodeattr_set(). If 1213 * \c attributes is \c MTAPI_NULL, then the following default 1214 * attributes will be used: 1215 * - all available cores will be used 1216 * - the main thread will be reused as a worker 1217 * - maximum number of tasks is 1024 1218 * - maximum number of groups is 128 1219 * - maximum number of queues is 16 1220 * - maximum queue capacity is 1024 1221 * - maximum number of priorities is 4. 1222 * 1223 * On success, \c *status is set to \c MTAPI_SUCCESS. On error, \c *status is 1224 * set to the appropriate error defined below. 1225 * Error code | Description 1226 * ----------------------------- | -------------------------------------------- 1227 * \c MTAPI_ERR_NODE_INITFAILED | MTAPI environment could not be initialized. 1228 * \c MTAPI_ERR_NODE_INITIALIZED | MTAPI environment was already initialized. 1229 * \c MTAPI_ERR_NODE_INVALID | The \c node_id parameter is not valid. 1230 * \c MTAPI_ERR_DOMAIN_INVALID | The \c domain_id parameter is not valid. 1231 * \c MTAPI_ERR_PARAMETER | Invalid mtapi_node_attributes or mtapi_info. 1232 * 1233 * \see mtapi_nodeattr_init(), mtapi_nodeattr_set() 1234 * 1235 * \notthreadsafe 1236 * \memory Allocates some memory depending on the node attributes. The amount 1237 * allocated is returned in the mtapi_info structure. 1238 * \ingroup RUNTIME_INIT_SHUTDOWN 1239 */ 1240 void mtapi_initialize( 1241 MTAPI_IN mtapi_domain_t domain_id, /**< [in] Domain id */ 1242 MTAPI_IN mtapi_node_t node_id, /**< [in] Node id */ 1243 MTAPI_IN mtapi_node_attributes_t* attributes, 1244 /**< [in] Pointer to attributes */ 1245 MTAPI_OUT mtapi_info_t* mtapi_info, /**< [out] Pointer to info struct */ 1246 MTAPI_OUT mtapi_status_t* status /**< [out] Pointer to error code, 1247 may be \c MTAPI_NULL */ 1248 ); 1249 1250 /** 1251 * Given a node and attribute number, returns a copy of the corresponding 1252 * attribute value in \c *attribute. 1253 * 1254 * See mtapi_nodeattr_set() for a list of predefined attribute numbers and the 1255 * sizes of the attribute values. The application is responsible for allocating 1256 * sufficient space for the returned attribute value and for setting 1257 * \c attribute_size to the exact size in bytes of the attribute value. 1258 * 1259 * On success, \c *status is set to \c MTAPI_SUCCESS and the attribute value 1260 * will be written to \c *attribute. On error, \c *status is set to the 1261 * appropriate error defined below and \c *attribute is undefined. 1262 * Error code | Description 1263 * ------------------------- | ------------------------------------------------ 1264 * \c MTAPI_ERR_PARAMETER | Invalid attribute parameter. 1265 * \c MTAPI_ERR_ATTR_NUM | Unknown attribute number. 1266 * \c MTAPI_ERR_ATTR_SIZE | Incorrect attribute size. 1267 * \c MTAPI_ERR_NODE_NOTINIT | The calling node is not initialized. 1268 * 1269 * \see mtapi_nodeattr_set() 1270 * 1271 * \waitfree 1272 * \ingroup RUNTIME_INIT_SHUTDOWN 1273 */ 1274 void mtapi_node_get_attribute( 1275 MTAPI_IN mtapi_node_t node, /**< [in] Node handle */ 1276 MTAPI_IN mtapi_uint_t attribute_num, /**< [in] Attribute id */ 1277 MTAPI_OUT void* attribute, /**< [out] Pointer to attribute value */ 1278 MTAPI_IN mtapi_size_t attribute_size,/**< [in] Size of attribute value */ 1279 MTAPI_OUT mtapi_status_t* status /**< [out] Pointer to error code, 1280 may be \c MTAPI_NULL */ 1281 ); 1282 1283 /** 1284 * Finalizes the MTAPI environment on a given MTAPI node and domain. 1285 * 1286 * It has to be called by each node using MTAPI. It is an error to call 1287 * mtapi_finalize() without first calling mtapi_initialize(). An MTAPI node 1288 * can call mtapi_finalize() once for each call to mtapi_initialize(), but it 1289 * is an error to call mtapi_finalize() multiple times from a given node 1290 * unless mtapi_initialize() has been called prior to each mtapi_finalize() 1291 * call. 1292 * 1293 * All tasks that have not completed and that have been started on the node 1294 * where mtapi_finalize() is called will be canceled 1295 * (see mtapi_task_cancel()). mtapi_finalize() blocks until all tasks that 1296 * have been started on the same node return (long-running tasks already 1297 * executing must actively poll the task state and return if canceled). Tasks 1298 * that execute actions on the node where mtapi_finalize() is called, also 1299 * block finalization of the MTAPI runtime system on that node. They are 1300 * canceled as well and return with an \c MTAPI_ERR_NODE_NOTINIT status. Other 1301 * functions that have a dependency to the node and that are called after 1302 * mtapi_finalize() also return \c MTAPI_ERR_NODE_NOTINIT (e.g., 1303 * mtapi_task_get() starting a task associated with an action implemented on 1304 * the already-finalized node). 1305 * 1306 * mtapi_finalize() may not be called from an action function. 1307 * 1308 * On success, \c *status is set to \c MTAPI_SUCCESS. On error, \c *status is 1309 * set to the appropriate error defined below. 1310 * Error code | Description 1311 * ----------------------------- | -------------------------------------------- 1312 * \c MTAPI_ERR_NODE_FINALFAILED | The MTAPI environment couldn't be finalized. 1313 * \c MTAPI_ERR_NODE_NOTINIT | The calling node is not initialized. 1314 * 1315 * \see mtapi_initialize(), mtapi_task_cancel(), mtapi_task_get() 1316 * 1317 * \notthreadsafe 1318 * \ingroup RUNTIME_INIT_SHUTDOWN 1319 */ 1320 void mtapi_finalize( 1321 MTAPI_OUT mtapi_status_t* status /**< [out] Pointer to error code, 1322 may be \c MTAPI_NULL */ 1323 ); 1324 1325 /** 1326 * Returns the domain id associated with the local node. 1327 * 1328 * On success, \c *status is set to \c MTAPI_SUCCESS. On error, \c *status is 1329 * set to the appropriate error defined below. 1330 * Error code | Description 1331 * ------------------------- | ------------------------------------------------ 1332 * \c MTAPI_ERR_NODE_NOTINIT | The calling node is not initialized. 1333 * 1334 * \returns Domain id of local node 1335 * \waitfree 1336 * \ingroup RUNTIME_INIT_SHUTDOWN 1337 */ 1338 mtapi_domain_t mtapi_domain_id_get( 1339 MTAPI_OUT mtapi_status_t* status /**< [out] Pointer to error code, 1340 may be \c MTAPI_NULL */ 1341 ); 1342 1343 /** 1344 * Returns the node id associated with the local node and domain. 1345 * 1346 * On success, \c *status is set to \c MTAPI_SUCCESS. On error, \c *status is 1347 * set to the appropriate error defined below. 1348 * Error code | Description 1349 * ------------------------- | ------------------------------------------------ 1350 * \c MTAPI_ERR_NODE_NOTINIT | The calling node is not initialized. 1351 * 1352 * \returns Node id of local node 1353 * \waitfree 1354 * \ingroup RUNTIME_INIT_SHUTDOWN 1355 */ 1356 mtapi_node_t mtapi_node_id_get( 1357 MTAPI_OUT mtapi_status_t* status /**< [out] Pointer to error code, 1358 may be \c MTAPI_NULL */ 1359 ); 1360 1361 1362 /* ---- ACTIONS ------------------------------------------------------------ */ 1363 1364 /** 1365 * \defgroup ACTIONS Actions 1366 * 1367 * \ingroup C_MTAPI 1368 * 1369 * Hardware or software implementations of jobs. 1370 * 1371 * An action is referenced by an opaque handle of type \c mtapi_action_hndl_t, 1372 * or indirectly through a handle to a job of type \c mtapi_job_hndl_t. A job 1373 * refers to all actions implementing the same job, regardless of the node(s) 1374 * where they are implemented. 1375 * 1376 * An action's lifetime begins when the application successfully calls 1377 * mtapi_action_create() and obtains a handle to the action. Its lifetime ends 1378 * upon successful completion of mtapi_action_delete() or mtapi_finalize(). 1379 * 1380 * While an opaque handle to an action may be used in the scope of one node 1381 * only, a job can be used to refer to all its associated actions implementing 1382 * the same job, regardless of the node where they are implemented. Tasks may 1383 * be invoked in this way from nodes that do not share memory or even the same 1384 * ISA with the node where the action resides. 1385 */ 1386 1387 /** 1388 * This function initializes an action attributes object. 1389 * 1390 * A action attributes object is a container of action attributes, optionally 1391 * passed to mtapi_action_create() to create an action with non-default 1392 * attributes. 1393 * 1394 * The application is responsible for allocating the 1395 * \c mtapi_action_attributes_t 1396 * object and initializing it with a call to mtapi_actionattr_init(). The 1397 * application may then call mtapi_actionattr_set() to specify action 1398 * attribute values. Calls to mtapi_actionattr_init() have no effect on action 1399 * attributes after the action has been created with mtapi_action_create(). The 1400 * \c mtapi_action_attributes_t object may safely be deleted by the application 1401 * after the call to mtapi_action_create(). 1402 * 1403 * On success, \c *status is set to \c MTAPI_SUCCESS. On error, \c *status is 1404 * set to the appropriate error defined below. 1405 * Error code | Description 1406 * ------------------------- | ------------------------------------------------ 1407 * \c MTAPI_ERR_PARAMETER | Invalid attributes parameter. 1408 * \c MTAPI_ERR_NODE_NOTINIT | The calling node is not initialized. 1409 * 1410 * \see mtapi_actionattr_set(), mtapi_action_create() 1411 * 1412 * \notthreadsafe 1413 * \memberof mtapi_action_attributes_struct 1414 */ 1415 void mtapi_actionattr_init( 1416 MTAPI_OUT mtapi_action_attributes_t* attributes, 1417 /**< [out] Pointer to attributes */ 1418 MTAPI_OUT mtapi_status_t* status /**< [out] Pointer to error code, 1419 may be \c MTAPI_NULL */ 1420 ); 1421 1422 /** 1423 * This function sets action attribute values in an action attributes object. 1424 * 1425 * An action attributes object is a container of action attributes, optionally 1426 * passed to mtapi_action_create() to create an action with non-default 1427 * attributes. 1428 * 1429 * See the table below for a list of predefined attribute numbers and the 1430 * sizes of the attribute values. The application must set \c attribute_size to 1431 * the exact size in bytes of the attribute value. Additional attributes may 1432 * be defined by the implementation. 1433 * 1434 * Calls to mtapi_actionattr_set() have no effect on action attributes after 1435 * the action has been created. The \c mtapi_action_attributes_t object may 1436 * safely be deleted by the application after the call to 1437 * mtapi_action_create(). 1438 * 1439 * MTAPI-defined action attributes: 1440 * <table> 1441 * <tr> 1442 * <th>Attribute num</th> 1443 * <th>Description</th> 1444 * <th>Data Type</th> 1445 * <th>Default</th> 1446 * </tr> 1447 * <tr> 1448 * <td>MTAPI_ACTION_GLOBAL</td> 1449 * <td>Indicates whether or not this is a globally visible action. Local 1450 * actions are not shared with other nodes.</td> 1451 * <td>mtapi_boolean_t</td> 1452 * <td>MTAPI_TRUE</td> 1453 * </tr> 1454 * <tr> 1455 * <td>MTAPI_ACTION_AFFINITY</td> 1456 * <td>Core affinity of action code.</td> 1457 * <td>mtapi_affinity_t</td> 1458 * <td>all cores set</td> 1459 * </tr> 1460 * <tr> 1461 * <td>MTAPI_DOMAIN_SHARED</td> 1462 * <td>Indicates whether or not the action is shareable across 1463 * domains.</td> 1464 * <td>mtapi_boolean_t</td> 1465 * <td>MTAPI_TRUE</td> 1466 * </tr> 1467 * </table> 1468 * 1469 * On success, \c *status is set to \c MTAPI_SUCCESS. On error, \c *status is 1470 * set to the appropriate error defined below. 1471 * Error code | Description 1472 * -------------------------- | ----------------------------------------------- 1473 * \c MTAPI_ERR_ATTR_READONLY | Attribute cannot be modified. 1474 * \c MTAPI_ERR_PARAMETER | Invalid attribute parameter. 1475 * \c MTAPI_ERR_ATTR_NUM | Unknown attribute number. 1476 * \c MTAPI_ERR_ATTR_SIZE | Incorrect attribute size. 1477 * \c MTAPI_ERR_NODE_NOTINIT | The calling node is not initialized. 1478 * 1479 * \see mtapi_action_create() 1480 * 1481 * \notthreadsafe 1482 * \memberof mtapi_action_attributes_struct 1483 */ 1484 void mtapi_actionattr_set( 1485 MTAPI_INOUT mtapi_action_attributes_t* attributes, 1486 /**< [in,out] Pointer to attributes */ 1487 MTAPI_IN mtapi_uint_t attribute_num, /**< [in] Attribute id */ 1488 MTAPI_IN void* attribute, /**< [in] Pointer to attribute value */ 1489 MTAPI_IN mtapi_size_t attribute_size, 1490 /**< [in] Size of attribute value. may 1491 be 0, attribute is interpreted as 1492 value in that case */ 1493 MTAPI_OUT mtapi_status_t* status /**< [out] Pointer to error code, 1494 may be \c MTAPI_NULL */ 1495 ); 1496 1497 /** 1498 * This function creates a software action (hardware actions are considered to 1499 * be pre-existent and do not need to be created). 1500 * 1501 * It is called on the node where the action function is implemented. An 1502 * action is an abstract encapsulation of everything needed to implement a 1503 * job. An action contains attributes, a reference to a job, a reference to an 1504 * action function, and a reference to node-local data. After an action is 1505 * created, it is referenced by the application using a node-local handle of 1506 * type \c mtapi_action_hndl_t, or indirectly through a node-local job handle 1507 * of type \c mtapi_job_hndl_t. An action's life-cycle begins with 1508 * mtapi_action_create(), and ends when mtapi_action_delete() or 1509 * mtapi_finalize() is called. 1510 * 1511 * To create an action, the application must supply the domain-wide job ID of 1512 * the job associated with the action. Job IDs must be predefined in the 1513 * application and runtime, of type \c mtapi_job_id_t, which is an 1514 * implementation-defined type. The job ID is unique in the sense that it is 1515 * unique for the job implemented by the action. However several actions may 1516 * implement the same job for load balancing purposes. 1517 * 1518 * For non-default behavior, \c *attributes must be prepared with 1519 * mtapi_actionattr_init() and mtapi_actionattr_set() prior to calling 1520 * mtapi_action_create(). If attributes is \c MTAPI_NULL, then default 1521 * attributes will be used. 1522 * 1523 * If \c node_local_data_size is not zero, \c node_local_data specifies the 1524 * start of node local data shared by action functions executed on the same 1525 * node. \c node_local_data_size can be used by the runtime for cache coherency 1526 * operations. 1527 * 1528 * On success, an action handle is returned and \c *status is set to 1529 * \c MTAPI_SUCCESS. On error, \c *status is set to the appropriate error 1530 * defined below. In the case where the action already exists, \c status will 1531 * be set to \c MTAPI_ERR_ACTION_EXISTS and the handle returned will not be a 1532 * valid handle. 1533 * <table> 1534 * <tr> 1535 * <th>Error code</th> 1536 * <th>Description</th> 1537 * </tr> 1538 * <tr> 1539 * <td>\c MTAPI_ERR_JOB_INVALID</td> 1540 * <td>The \c job_id is not a valid job ID, i.e., no action was created for 1541 * that ID or the action has been deleted.</td> 1542 * </tr> 1543 * <tr> 1544 * <td>\c MTAPI_ERR_ACTION_EXISTS</td> 1545 * <td>This action is already created.</td> 1546 * </tr> 1547 * <tr> 1548 * <td>\c MTAPI_ERR_ACTION_LIMIT</td> 1549 * <td>Exceeded maximum number of actions allowed.</td> 1550 * </tr> 1551 * <tr> 1552 * <td>\c MTAPI_ERR_ACTION_NOAFFINITY</td> 1553 * <td>The action was created with an \c MTAPI_ACTION_AFFINITY attribute 1554 * that has set the affinity to all cores of the node to 1555 * \c MTAPI_FALSE.</td> 1556 * </tr> 1557 * <tr> 1558 * <td>\c MTAPI_ERR_NODE_NOTINIT</td> 1559 * <td>The calling node is not initialized.</td> 1560 * </tr> 1561 * <tr> 1562 * <td>\c MTAPI_ERR_PARAMETER</td> 1563 * <td>Invalid attributes parameter.</td> 1564 * </tr> 1565 * </table> 1566 * 1567 * \see mtapi_actionattr_init(), mtapi_actionattr_set(), mtapi_action_delete(), 1568 * mtapi_finalize() 1569 * 1570 * \returns Handle to newly created action, invalid handle on error 1571 * \threadsafe 1572 * \ingroup ACTIONS 1573 */ 1574 mtapi_action_hndl_t mtapi_action_create( 1575 MTAPI_IN mtapi_job_id_t job_id, /**< [in] Job id */ 1576 MTAPI_IN mtapi_action_function_t function, 1577 /**< [in] Action function pointer */ 1578 MTAPI_IN void* node_local_data, /**< [in] Data shared across tasks */ 1579 MTAPI_IN mtapi_size_t node_local_data_size, 1580 /**< [in] Size of shared data */ 1581 MTAPI_IN mtapi_action_attributes_t* attributes, 1582 /**< [in] Pointer to attributes */ 1583 MTAPI_OUT mtapi_status_t* status /**< [out] Pointer to error code, 1584 may be \c MTAPI_NULL */ 1585 ); 1586 1587 /** 1588 * This function changes the value of the attribute that corresponds to the 1589 * given \c attribute_num for this action. 1590 * 1591 * \c attribute must point to the attribute value, and \c attribute_size must 1592 * be set to the exact size of the attribute value. See mtapi_actionattr_set() 1593 * for a list of predefined attribute numbers and the sizes of their values. 1594 * 1595 * On success, \c *status is set to \c MTAPI_SUCCESS. On error, \c *status is 1596 * set to the appropriate error defined below. 1597 * Error code | Description 1598 * --------------------------- | ---------------------------------------------- 1599 * \c MTAPI_ERR_PARAMETER | Invalid attribute parameter. 1600 * \c MTAPI_ERR_ACTION_INVALID | Argument is not a valid action handle. 1601 * \c MTAPI_ERR_ATTR_NUM | Unknown attribute number. 1602 * \c MTAPI_ERR_ATTR_SIZE | Incorrect attribute size. 1603 * \c MTAPI_ERR_NODE_NOTINIT | The calling node is not initialized. 1604 * 1605 * \see mtapi_actionattr_set() 1606 * 1607 * \notthreadsafe 1608 * \ingroup ACTIONS 1609 */ 1610 void mtapi_action_set_attribute( 1611 MTAPI_IN mtapi_action_hndl_t action, /**< [in] Action handle */ 1612 MTAPI_IN mtapi_uint_t attribute_num, /**< [in] Attribute id */ 1613 MTAPI_IN void* attribute, /**< [in] Pointer to attribute value */ 1614 MTAPI_IN mtapi_size_t attribute_size, 1615 /**< [in] Size of attribute value. may 1616 be 0, attribute is interpreted as 1617 value in that case */ 1618 MTAPI_OUT mtapi_status_t* status /**< [out] Pointer to error code, 1619 may be \c MTAPI_NULL */ 1620 ); 1621 1622 /** 1623 * Returns the attribute value that corresponds to the given \c attribute_num 1624 * for this action. 1625 * 1626 * \c attribute must point to the location where the attribute value is to be 1627 * returned, and \c attribute_size must be set to the exact size of the 1628 * attribute value. See mtapi_actionattr_set() for a list of predefined 1629 * attribute numbers and the sizes of their values. 1630 * 1631 * On success, \c *status is set to \c MTAPI_SUCCESS and the attribute value is 1632 * returned in \c *attribute. On error, \c *status is set to the appropriate 1633 * error defined below and \c *attribute is undefined. 1634 * Error code | Description 1635 * --------------------------- | ---------------------------------------------- 1636 * \c MTAPI_ERR_PARAMETER | Invalid attribute parameter. 1637 * \c MTAPI_ERR_ACTION_INVALID | Argument is not a valid action handle. 1638 * \c MTAPI_ERR_ATTR_NUM | Unknown attribute number. 1639 * \c MTAPI_ERR_ATTR_SIZE | Incorrect attribute size. 1640 * \c MTAPI_ERR_NODE_NOTINIT | The calling node is not initialized. 1641 * 1642 * \see mtapi_actionattr_set() 1643 * 1644 * \waitfree 1645 * \ingroup ACTIONS 1646 */ 1647 void mtapi_action_get_attribute( 1648 MTAPI_IN mtapi_action_hndl_t action, /**< [in] Action handle */ 1649 MTAPI_IN mtapi_uint_t attribute_num, /**< [in] Attribute id */ 1650 MTAPI_OUT void* attribute, /**< [out] Pointer to attribute value */ 1651 MTAPI_IN mtapi_size_t attribute_size,/**< [in] Size of attribute value */ 1652 MTAPI_OUT mtapi_status_t* status /**< [out] Pointer to error code, 1653 may be \c MTAPI_NULL */ 1654 ); 1655 1656 /** 1657 * This function deletes a software action (Hardware actions exist perpetually 1658 * and cannot be deleted). 1659 * 1660 * mtapi_action_delete() may be called by any node that has a valid action 1661 * handle. Tasks associated with an action that has been deleted may still be 1662 * executed depending on their internal state: 1663 * - If mtapi_action_delete() is called on an action that is currently 1664 * executing, the associated task's state will be set to 1665 * \c MTAPI_TASK_CANCELLED and execution will continue. To accomplish this, 1666 * action functions must poll the task state with 1667 * mtapi_context_taskstate_get(). A call to mtapi_task_wait() on the task 1668 * executing this code will return the status set by 1669 * mtapi_context_status_set(), or \c MTAPI_SUCCESS if not explicitly set. 1670 * - Tasks that are started or enqueued but waiting for execution by the 1671 * MTAPI runtime when mtapi_action_delete() is called will not be executed 1672 * anymore if the deleted action is the only action associated with that 1673 * task. A call to mtapi_task_wait() will return the status 1674 * \c MTAPI_ERR_ACTION_DELETED. 1675 * - Tasks that are started or enqueued after deletion of the action will 1676 * return \c MTAPI_ERR_ACTION_INVALID if the deleted action is the only 1677 * action associated with that task. 1678 * 1679 * Calling mtapi_action_get_attribute() on a deleted action will return 1680 * \c MTAPI_ERR_ACTION_INVALID if all actions implementing the job had been 1681 * deleted. 1682 * 1683 * The function mtapi_action_delete() blocks until the corresponding action 1684 * code is left by all tasks that are executing the code or until the timeout 1685 * is reached. If \c timeout is a constant 0 or the symbolic constant 1686 * \c MTAPI_NOWAIT, this function only returns \c MTAPI_SUCCESS if no tasks are 1687 * executing the action when it is called. If it is set to \c MTAPI_INFINITE, 1688 * the function may block infinitely. 1689 * 1690 * On success, \c *status is set to \c MTAPI_SUCCESS. On error, \c *status is 1691 * set to the appropriate error defined below. 1692 * Error code | Description 1693 * --------------------------- | ---------------------------------------------- 1694 * \c MTAPI_ERR_ACTION_INVALID | Argument is not a valid action handle. 1695 * \c MTAPI_TIMEOUT | Timeout was reached. 1696 * \c MTAPI_ERR_NODE_NOTINIT | The calling node is not initialized. 1697 * 1698 * \see mtapi_context_taskstate_get(), mtapi_context_status_set(), 1699 * mtapi_task_wait() 1700 * 1701 * \threadsafe 1702 * \ingroup ACTIONS 1703 */ 1704 void mtapi_action_delete( 1705 MTAPI_IN mtapi_action_hndl_t action, /**< [in] Action handle */ 1706 MTAPI_IN mtapi_timeout_t timeout, /**< [in] Timeout duration in 1707 milliseconds */ 1708 MTAPI_OUT mtapi_status_t* status /**< [out] Pointer to error code, 1709 may be \c MTAPI_NULL */ 1710 ); 1711 1712 /** 1713 * This function disables an action. 1714 * 1715 * Tasks associated with an action that has been disabled may still be 1716 * executed depending on their internal state: 1717 * - If mtapi_action_disable() is called on an action that is currently 1718 * executing, the associated task's state will be set to 1719 * \c MTAPI_TASK_CANCELLED and execution will continue. To accomplish this, 1720 * action functions must poll the task with mtapi_context_taskstate_get(). 1721 * A call to mtapi_task_wait() on the task executing this code will return 1722 * the status set by mtapi_context_status_set(), or \c MTAPI_SUCCESS if not 1723 * explicitly set. 1724 * - Tasks that are started or enqueued but waiting for execution by the 1725 * MTAPI runtime when mtapi_action_disable() is called will not be executed 1726 * anymore if the disabled action is the only action associated with that 1727 * task. A call to mtapi_task_wait() will return the status 1728 * \c MTAPI_ERR_ACTION_DISABLED. 1729 * - Tasks that are started or enqueued after the action has been disabled 1730 * will return \c MTAPI_ERR_ACTION_DISABLED if either the disabled action is 1731 * the only action associated with a task or all actions associated with a 1732 * task are disabled. 1733 * mtapi_action_disable() blocks until all running tasks exit the code, or 1734 * until the timeout is reached. If timeout is the constant 0 or the symbolic 1735 * constant \c MTAPI_NOWAIT, this function only returns \c MTAPI_SUCCESS if no 1736 * tasks are executing the action when it is called. If it is set to 1737 * \c MTAPI_INFINITE the function may block infinitely. 1738 * 1739 * On success, \c *status is set to \c MTAPI_SUCCESS. On error, \c *status is 1740 * set to the appropriate error defined below. 1741 * Error code | Description 1742 * --------------------------- | ---------------------------------------------- 1743 * \c MTAPI_ERR_ACTION_INVALID | Argument is not a valid action handle. 1744 * \c MTAPI_TIMEOUT | Timeout was reached. 1745 * \c MTAPI_ERR_NODE_NOTINIT | The calling node is not initialized. 1746 * 1747 * \see mtapi_context_taskstate_get(), mtapi_context_status_set(), 1748 * mtapi_task_wait() 1749 * 1750 * \waitfree 1751 * \ingroup ACTIONS 1752 */ 1753 void mtapi_action_disable( 1754 MTAPI_IN mtapi_action_hndl_t action, /**< [in] Action handle */ 1755 MTAPI_IN mtapi_timeout_t timeout, /**< [in] Timeout duration in 1756 milliseconds */ 1757 MTAPI_OUT mtapi_status_t* status /**< [out] Pointer to error code, 1758 may be \c MTAPI_NULL */ 1759 ); 1760 1761 /** 1762 * This function enables a previously disabled action. 1763 * 1764 * If this function is called on an action that no longer exists, an 1765 * \c MTAPI_ERR_ACTION_INVALID error will be returned. 1766 * 1767 * On success, \c *status is set to \c MTAPI_SUCCESS. On error, \c *status is 1768 * set to the appropriate error defined below. 1769 * Error code | Description 1770 * --------------------------- | ---------------------------------------------- 1771 * \c MTAPI_ERR_ACTION_INVALID | Argument is not a valid action handle. 1772 * \c MTAPI_ERR_NODE_NOTINIT | The calling node is not initialized. 1773 * 1774 * \waitfree 1775 * \ingroup ACTIONS 1776 */ 1777 void mtapi_action_enable( 1778 MTAPI_IN mtapi_action_hndl_t action, /**< [in] Action handle */ 1779 MTAPI_OUT mtapi_status_t* status /**< [out] Pointer to error code, 1780 may be \c MTAPI_NULL */ 1781 ); 1782 1783 /** 1784 * \defgroup ACTION_FUNCTIONS Action Functions 1785 * 1786 * \ingroup C_MTAPI 1787 * 1788 * Executable software functions that implement actions. 1789 * 1790 * The runtime passes arguments to the action function when a task is started. 1791 * Passing arguments from one node to another node should be implemented as a 1792 * copy operation. Just as the arguments are passed before start of execution, 1793 * the result buffer is copied back to the calling node after the action 1794 * function terminates. In shared memory environments, the copying of data in 1795 * both cases is not necessary. The node-local data is data used by several 1796 * action functions being executed on the same node (or at least in the same 1797 * address space). The shared data is specified when the action is created. 1798 * 1799 * An action function can interact with the runtime environment through a task 1800 * context object of type \c mtapi_task_context_t. A task context object is 1801 * allocated and managed by the runtime. The runtime passes a pointer to the 1802 * context object when the action function is invoked.The action may then 1803 * query information about the execution context(e.g., its core number, the 1804 * number of tasks and task number in a multi - instance task, polling the 1805 * task state) by calling the \c mtapi_context_* functions. Furthermore it is 1806 * possible to pass information from the action function to the runtime system 1807 * which is executing the action function(setting the status manually, for 1808 * example). All of these \c mtapi_context_* functions are called in the 1809 * context of task execution. 1810 */ 1811 1812 /** 1813 * This function can be called from an action function to set the status that 1814 * can be obtained by a subsequent call to mtapi_task_wait() or 1815 * mtapi_group_wait_any(). 1816 * 1817 * \c task_context must be the same value as the context parameter that the 1818 * runtime passes to the action function when it is invoked. 1819 * 1820 * The status can be passed from the action function to the runtime system by 1821 * setting error_code to one of the following values: 1822 * - \c MTAPI_SUCCESS for successful completion 1823 * - \c MTAPI_ERR_ACTION_CANCELLED if the action execution is canceled 1824 * - \c MTAPI_ERR_ACTION_FAILED if the task could not be completed as intended 1825 * The error code will be especially important in future versions of MTAPI 1826 * where tasks shall be chained (flow graphs). The chain execution can then be 1827 * aborted if the error code is not \c MTAPI_SUCCESS. 1828 * 1829 * On success, \c *status is set to \c MTAPI_SUCCESS. On error, \c *status is 1830 * set to the appropriate error defined below. 1831 * <table> 1832 * <tr> 1833 * <th>Error code</th> 1834 * <th>Description</th> 1835 * </tr> 1836 * <tr> 1837 * <td>\c MTAPI_ERR_CONTEXT_OUTOFCONTEXT</td> 1838 * <td>Not called in the context of a task execution. This function must 1839 * be used in an action function only. The action function must be 1840 * called from the MTAPI runtime system.</td> 1841 * </tr> 1842 * <tr> 1843 * <td>\c MTAPI_ERR_NODE_NOTINIT</td> 1844 * <td>The calling node is not initialized.</td> 1845 * </tr> 1846 * </table> 1847 * 1848 * \see mtapi_task_wait(), mtapi_group_wait_any() 1849 * 1850 * \notthreadsafe 1851 * \ingroup ACTION_FUNCTIONS 1852 */ 1853 void mtapi_context_status_set( 1854 MTAPI_INOUT mtapi_task_context_t* task_context, 1855 /**< [in,out] Pointer to task context */ 1856 MTAPI_IN mtapi_status_t error_code, /**< [in] Task return value */ 1857 MTAPI_OUT mtapi_status_t* status /**< [out] Pointer to error code, 1858 may be \c MTAPI_NULL */ 1859 ); 1860 1861 /** 1862 * This function can be called from an action function to notify the runtime 1863 * system. 1864 * 1865 * This is used to communicate certain states to the runtime implementation to 1866 * allow it to optimize task execution. 1867 * 1868 * \c task_context must be the same value as the context parameter that the 1869 * runtime passes to the action function when it is invoked. 1870 * 1871 * The underlying type \c mtapi_notification_t and the valid values for 1872 * notification are implementation-defined. The notification system is meant 1873 * to be flexible, and can be used in many ways, for example: 1874 * - To trigger prefetching of data for further processing 1875 * - To order execution via queues there might be point in the action code 1876 * where the next task in the queue may be started, even if the current 1877 * code, started from the same queue, is still executing 1878 * 1879 * On success, \c *status is set to \c MTAPI_SUCCESS. On error, \c *status is 1880 * set to the appropriate error defined below. 1881 * <table> 1882 * <tr> 1883 * <th>Error code</th> 1884 * <th>Description</th> 1885 * </tr> 1886 * <tr> 1887 * <td>\c MTAPI_ERR_CONTEXT_OUTOFCONTEXT</td> 1888 * <td>Not called in the context of a task execution. This function must 1889 * be used in an action function only. The action function must be 1890 * called from the MTAPI runtime system.</td> 1891 * </tr> 1892 * <tr> 1893 * <td>\c MTAPI_ERR_NODE_NOTINIT</td> 1894 * <td>The calling node is not initialized.</td> 1895 * </tr> 1896 * </table> 1897 * 1898 * \notthreadsafe 1899 * \ingroup ACTION_FUNCTIONS 1900 */ 1901 void mtapi_context_runtime_notify( 1902 MTAPI_IN mtapi_task_context_t* task_context, 1903 /**< [in] Pointer to task context */ 1904 MTAPI_IN mtapi_notification_t notification, 1905 /**< [in] Notification id */ 1906 MTAPI_IN void* data, /**< [in] Pointer to associated data */ 1907 MTAPI_IN mtapi_size_t data_size, /**< [in] Size of data */ 1908 MTAPI_OUT mtapi_status_t* status /**< [out] Pointer to error code, 1909 may be \c MTAPI_NULL */ 1910 ); 1911 1912 /** 1913 * An action function may call this function to obtain the state of the task 1914 * that is associated with the action function. 1915 * 1916 * \c task_context must be the same value as the context parameter that the 1917 * runtime passes to the action function when it is invoked. 1918 * 1919 * The underlying representation of type \c mtapi_task_state_t is 1920 * implementation-defined. Values of type \c mtapi_task_state_t may be copied, 1921 * assigned, and compared with other values of type \c mtapi_task_state_t, but 1922 * the caller should make no other assumptions about its type or contents. A 1923 * minimal implementation must return a status of \c MTAPI_TASK_CANCELLED if 1924 * the task is canceled, and \c MTAPI_TASK_RUNNING otherwise. Other values of 1925 * the task state are implementation-defined. This task state can be used to 1926 * abort a long running computation inside an action function. 1927 * 1928 * On success, \c *status is set to \c MTAPI_SUCCESS. On error, \c *status is 1929 * set to the appropriate error defined below. 1930 * <table> 1931 * <tr> 1932 * <th>Error code</th> 1933 * <th>Description</th> 1934 * </tr> 1935 * <tr> 1936 * <td>\c MTAPI_ERR_CONTEXT_OUTOFCONTEXT</td> 1937 * <td>Not called in the context of a task execution. This function must 1938 * be used in an action function only. The action function must be 1939 * called from the MTAPI runtime system.</td> 1940 * </tr> 1941 * <tr> 1942 * <td>\c MTAPI_ERR_NODE_NOTINIT</td> 1943 * <td>The calling node is not initialized.</td> 1944 * </tr> 1945 * </table> 1946 * 1947 * \returns Task state of current context 1948 * \notthreadsafe 1949 * \ingroup ACTION_FUNCTIONS 1950 */ 1951 mtapi_task_state_t mtapi_context_taskstate_get( 1952 MTAPI_IN mtapi_task_context_t* task_context, 1953 /**< [in] Pointer to task context */ 1954 MTAPI_OUT mtapi_status_t* status /**< [out] Pointer to error code, 1955 may be \c MTAPI_NULL */ 1956 ); 1957 1958 /** 1959 * This function can be called from an action function to query the instance 1960 * number of the associated task. 1961 * 1962 * A task can have multiple instances (multi-instance tasks), in which case 1963 * the same job is executed multiple times in parallel. Each instance has a 1964 * number, and this function gives the instance number. Task instances are 1965 * numbered sequentially, starting at zero. 1966 * 1967 * \c task_context must be the same value as the context parameter that the 1968 * runtime passes to the action function when it is invoked. 1969 * 1970 * On success, \c *status is set to \c MTAPI_SUCCESS and the task instance 1971 * number is returned. On error, \c *status is set to the appropriate error 1972 * defined below. 1973 * <table> 1974 * <tr> 1975 * <th>Error code</th> 1976 * <th>Description</th> 1977 * </tr> 1978 * <tr> 1979 * <td>\c MTAPI_ERR_CONTEXT_OUTOFCONTEXT</td> 1980 * <td>Not called in the context of a task execution. This function must 1981 * be used in an action function only. The action function must be 1982 * called from the MTAPI runtime system.</td> 1983 * </tr> 1984 * <tr> 1985 * <td>\c MTAPI_ERR_NODE_NOTINIT</td> 1986 * <td>The calling node is not initialized.</td> 1987 * </tr> 1988 * </table> 1989 * 1990 * \returns Instance number of current task 1991 * \notthreadsafe 1992 * \ingroup ACTION_FUNCTIONS 1993 */ 1994 mtapi_uint_t mtapi_context_instnum_get( 1995 MTAPI_IN mtapi_task_context_t* task_context, 1996 /**< [in] Pointer to task context */ 1997 MTAPI_OUT mtapi_status_t* status /**< [out] Pointer to error code, 1998 may be \c MTAPI_NULL */ 1999 ); 2000 2001 /** 2002 * This function can be called from an action function to query the total 2003 * number of parallel task instances. 2004 * 2005 * This value is greater than one for multi-instance tasks. 2006 * 2007 * On success, \c *status is set to \c MTAPI_SUCCESS. On error, \c *status is 2008 * set to the appropriate error defined below. 2009 * <table> 2010 * <tr> 2011 * <th>Error code</th> 2012 * <th>Description</th> 2013 * </tr> 2014 * <tr> 2015 * <td>\c MTAPI_ERR_CONTEXT_OUTOFCONTEXT</td> 2016 * <td>Not called in the context of a task execution. This function must 2017 * be used in an action function only. The action function must be 2018 * called from the MTAPI runtime system.</td> 2019 * </tr> 2020 * <tr> 2021 * <td>\c MTAPI_ERR_NODE_NOTINIT</td> 2022 * <td>The calling node is not initialized.</td> 2023 * </tr> 2024 * </table> 2025 * 2026 * \returns Total number of parallel task instances 2027 * \notthreadsafe 2028 * \ingroup ACTION_FUNCTIONS 2029 */ 2030 mtapi_uint_t mtapi_context_numinst_get( 2031 MTAPI_IN mtapi_task_context_t* task_context, 2032 /**< [in] Pointer to task context */ 2033 MTAPI_OUT mtapi_status_t* status /**< [out] Pointer to error code, 2034 may be \c MTAPI_NULL */ 2035 ); 2036 2037 /** 2038 * This function can be called from an action function to query the current 2039 * core number for debugging purposes. 2040 * 2041 * The core numbering is implementation-defined. 2042 * 2043 * \c task_context must be the same value as the context parameter that the 2044 * runtime passes to the action function when it was invoked. 2045 * 2046 * On success, \c *status is set to \c MTAPI_SUCCESS. On error, \c *status is 2047 * set to the appropriate error defined below. 2048 * <table> 2049 * <tr> 2050 * <th>Error code</th> 2051 * <th>Description</th> 2052 * </tr> 2053 * <tr> 2054 * <td>\c MTAPI_ERR_CONTEXT_OUTOFCONTEXT</td> 2055 * <td>Not called in the context of a task execution. This function must 2056 * be used in an action function only. The action function must be 2057 * called from the MTAPI runtime system.</td> 2058 * </tr> 2059 * <tr> 2060 * <td>\c MTAPI_ERR_NODE_NOTINIT</td> 2061 * <td>The calling node is not initialized.</td> 2062 * </tr> 2063 * </table> 2064 * 2065 * \returns Worker thread index the current task is running on 2066 * \notthreadsafe 2067 * \ingroup ACTION_FUNCTIONS 2068 */ 2069 mtapi_uint_t mtapi_context_corenum_get( 2070 MTAPI_IN mtapi_task_context_t* task_context, 2071 /**< [in] Pointer to task context */ 2072 MTAPI_OUT mtapi_status_t* status /**< [out] Pointer to error code, 2073 may be \c MTAPI_NULL */ 2074 ); 2075 2076 2077 /* ---- CORE AFFINITY MASKS ------------------------------------------------ */ 2078 2079 /** 2080 * \defgroup CORE_AFFINITY_MASKS Core Affinities 2081 * 2082 * \ingroup C_MTAPI 2083 * 2084 * Affinities for executing action functions on subsets of cores. 2085 * 2086 * To set core affinities, the application must allocate an affinity mask 2087 * object of type \c mtapi_affinity_t and initialize it with a call to 2088 * mtapi_affinity_init(). Affinities are specified by calling 2089 * mtapi_affinity_set(). The application must also allocate and initialize an 2090 * action attributes object of type \c mtapi_action_attributes_t. The affinity 2091 * mask object is then passed to mtapi_actionattr_set() to set the prescribed 2092 * affinities in the action attributes object. The action attributes object is 2093 * then passed to mtapi_action_create() to create a new action with those 2094 * attributes. 2095 * 2096 * It is in the nature of core affinities to be highly hardware dependent. The 2097 * least common denominator for different architectures is enabling and 2098 * disabling core numbers in the affinity mask. Action-to-core affinities can 2099 * be set via the action attribute \c MTAPI_ACTION_AFFINITY during the creation 2100 * of an action. 2101 */ 2102 2103 /** 2104 * This function initializes an affinity mask object. 2105 * 2106 * The affinity to all cores will be initialized to the value of affinity. 2107 * This function should be called prior to calling mtapi_affinity_set() to 2108 * specify non-default affinity settings. The affinity mask object may then 2109 * be used to set the \c MTAPI_ACTION_AFFINITY attribute when creating an 2110 * action with mtapi_action_create(). 2111 * 2112 * On success, \c *status is set to \c MTAPI_SUCCESS. On error, \c *status is 2113 * set to the appropriate error defined below. 2114 * Error code | Description 2115 * -------------------------- | ----------------------------------------------- 2116 * \c MTAPI_ERR_AFFINITY_MASK | Invalid mask parameter. 2117 * \c MTAPI_ERR_NODE_NOTINIT | The calling node is not initialized. 2118 * 2119 * \see mtapi_affinity_set(), mtapi_action_create() 2120 * 2121 * \notthreadsafe 2122 * \ingroup CORE_AFFINITY_MASKS 2123 */ 2124 void mtapi_affinity_init( 2125 MTAPI_OUT mtapi_affinity_t* mask, /**< [out] Pointer to affinity mask */ 2126 MTAPI_IN mtapi_boolean_t affinity, /**< [in] Initial affinity */ 2127 MTAPI_OUT mtapi_status_t* status /**< [out] Pointer to error code, 2128 may be \c MTAPI_NULL */ 2129 ); 2130 2131 /** 2132 * This function is used to change the default values of an affinity mask 2133 * object. 2134 * 2135 * The affinity mask object can then be passed to mtapi_actionattr_set() to 2136 * set the \c MTAPI_ACTION_AFFINITY action attribute. An action function will 2137 * be executed on a core only if the core's affinity is set to \c MTAPI_TRUE. 2138 * Calls to mtapi_affinity_set() have no effect on action attributes after the 2139 * action has been created. 2140 * 2141 * \c mask must be a pointer to an affinity mask object previously initialized 2142 * with mtapi_affinity_init(). 2143 * 2144 * The \c core_num is a hardware- and implementation-specific numeric 2145 * identifier for a single core of the current node. 2146 * 2147 * On success, \c *status is set to \c MTAPI_SUCCESS. On error, \c *status is 2148 * set to the appropriate error defined below. 2149 * Error code | Description 2150 * -------------------------- | ----------------------------------------------- 2151 * \c MTAPI_ERR_AFFINITY_MASK | Invalid mask parameter. 2152 * \c MTAPI_ERR_CORE_NUM | Unknown core number. 2153 * \c MTAPI_ERR_NODE_NOTINIT | The calling node is not initialized. 2154 * 2155 * \see mtapi_actionattr_set(), mtapi_affinity_init() 2156 * 2157 * \notthreadsafe 2158 * \ingroup CORE_AFFINITY_MASKS 2159 */ 2160 void mtapi_affinity_set( 2161 MTAPI_INOUT mtapi_affinity_t* mask, /**< [in, out] Pointer to affinity 2162 mask */ 2163 MTAPI_IN mtapi_uint_t core_num, /**< [in] Core number */ 2164 MTAPI_IN mtapi_boolean_t affinity, /**< [in] Affinity to given core */ 2165 MTAPI_OUT mtapi_status_t* status /**< [out] Pointer to error code, 2166 may be \c MTAPI_NULL */ 2167 ); 2168 2169 /** 2170 * Returns the affinity that corresponds to the given \c core_num for this 2171 * affinity mask. 2172 * 2173 * \c mask is a pointer to an affinity mask object previously initialized with 2174 * mtapi_affinity_init(). 2175 * 2176 * Note that affinities may be queried but may not be changed for an action 2177 * after it has been created. If affinities need to be modified at runtime, 2178 * new actions must be created. 2179 * 2180 * On success, \c *status is set to \c MTAPI_SUCCESS. On error, \c *status is 2181 * set to the appropriate error defined below. 2182 * Error code | Description 2183 * -------------------------- | ----------------------------------------------- 2184 * \c MTAPI_ERR_AFFINITY_MASK | Invalid mask parameter. 2185 * \c MTAPI_ERR_CORE_NUM | Unknown core number. 2186 * \c MTAPI_ERR_NODE_NOTINIT | The calling node is not initialized. 2187 * 2188 * \see mtapi_affinity_init() 2189 * 2190 * \returns \c MTAPI_TRUE if affinity to \c core_num is set, \c MTAPI_FALSE 2191 * otherwise 2192 * \waitfree 2193 * \ingroup CORE_AFFINITY_MASKS 2194 */ 2195 mtapi_boolean_t mtapi_affinity_get( 2196 MTAPI_OUT mtapi_affinity_t* mask, /**< [out] Pointer to affinity mask */ 2197 MTAPI_IN mtapi_uint_t core_num, /**< [in] Core number */ 2198 MTAPI_OUT mtapi_status_t* status /**< [out] Pointer to error code, 2199 may be \c MTAPI_NULL */ 2200 ); 2201 2202 2203 /* ---- QUEUES ------------------------------------------------------------- */ 2204 2205 /** 2206 * \defgroup QUEUES Queues 2207 * 2208 * \ingroup C_MTAPI 2209 * 2210 * Queues for controlling the scheduling policy of tasks. 2211 * 2212 * The default scheduling policy for queues is ordered task execution. Tasks 2213 * that have to be executed sequentially are enqueued into the same queue. In 2214 * this case every queue is associated with exactly one action. Tasks started 2215 * via different queues can be executed in parallel. This is needed for packet 2216 * processing applications, for example: each stream is processed by one 2217 * queue. This ensures sequential processing of packets belonging to the same 2218 * stream. Different streams are processed in parallel. 2219 * 2220 * Queues were made explicit in MTAPI. This allows mapping of queues onto 2221 * hardware queues, if available. One MTAPI queue is associated with one 2222 * action, or for purposes of load balancing, with actions implementing the 2223 * same job on different nodes. 2224 */ 2225 2226 /** 2227 * This function initializes a queue attributes object. 2228 * 2229 * A queue attributes object is a container of queue attributes, optionally 2230 * passed to mtapi_queue_create() to create a queue with non-default 2231 * attributes. 2232 * 2233 * The application is responsible for allocating the 2234 * \c mtapi_queue_attributes_t 2235 * object and initializing it with a call to mtapi_queueattr_init(). The 2236 * application may then call mtapi_queueattr_set() to specify queue attribute 2237 * values. Calls to mtapi_queueattr_init() have no effect on queue attributes 2238 * after the queue has been created. To change an attribute of an existing 2239 * queue, see mtapi_queue_set_attribute(). The \c mtapi_queue_attributes_t 2240 * object may safely be deleted by the application after the call to 2241 * mtapi_queue_create(). 2242 * 2243 * On success, \c *status is set to \c MTAPI_SUCCESS. On error, \c *status is 2244 * set to the appropriate error defined below. 2245 * Error code | Description 2246 * ------------------------- | ------------------------------------------------ 2247 * \c MTAPI_ERR_PARAMETER | Invalid attributes parameter. 2248 * \c MTAPI_ERR_NODE_NOTINIT | The calling node is not initialized. 2249 * 2250 * \see mtapi_queue_create(), mtapi_queueattr_set(), 2251 * mtapi_queue_set_attribute() 2252 * 2253 * \notthreadsafe 2254 * \memberof mtapi_queue_attributes_struct 2255 */ 2256 void mtapi_queueattr_init( 2257 MTAPI_OUT mtapi_queue_attributes_t* attributes, 2258 /**< [out] Pointer to attributes */ 2259 MTAPI_OUT mtapi_status_t* status /**< [out] Pointer to error code, 2260 may be \c MTAPI_NULL */ 2261 ); 2262 2263 /** 2264 * This function sets queue attribute values in a queue attributes object. 2265 * 2266 * A queue attributes object is a container of queue attributes, optionally 2267 * passed to mtapi_queue_create() to create a queue with non-default 2268 * attributes. 2269 * 2270 * \c attributes must be a pointer to a queue attributes object previously 2271 * initialized by mtapi_queueattr_init(). 2272 * 2273 * See the table below for a list of predefined attribute numbers and the 2274 * sizes of the attribute values. The application must set \c attribute_size to 2275 * the exact size in bytes of the attribute value. Additional attributes may 2276 * be defined by the implementation. 2277 * 2278 * Calls to mtapi_queueattr_set() have no effect on queue attributes once the 2279 * queue has been created. The \c mtapi_queue_attributes_t object may safely be 2280 * deleted by the application after the call to mtapi_queue_create(). 2281 * 2282 * MTAPI-defined queue attributes: 2283 * <table> 2284 * <tr> 2285 * <th>Attribute num</th> 2286 * <th>Description</th> 2287 * <th>Data Type</th> 2288 * <th>Default</th> 2289 * </tr> 2290 * <tr> 2291 * <td>\c MTAPI_QUEUE_GLOBAL</td> 2292 * <td>Indicates if this is a globally visible queue. Only global queues 2293 * are shared with other nodes.</td> 2294 * <td>\c mtapi_boolean_t</td> 2295 * <td>\c MTAPI_TRUE</td> 2296 * </tr> 2297 * <tr> 2298 * <td>\c MTAPI_QUEUE_PRIORITY</td> 2299 * <td>Priority of the queue.</td> 2300 * <td>\c mtapi_uint_t</td> 2301 * <td>0(default priority)</td> 2302 * </tr> 2303 * <tr> 2304 * <td>MTAPI_QUEUE_LIMIT</td> 2305 * <td>Max. number of elements in the queue; the queue blocks on queuing 2306 * more items.</td> 2307 * <td>\c mtapi_uint_t</td> 2308 * <td>0(0 stands for 'unlimited')</td> 2309 * </tr> 2310 * <tr> 2311 * <td>\c MTAPI_QUEUE_ORDERED</td> 2312 * <td>Specify if the queue is order-preserving.</td> 2313 * <td>\c mtapi_boolean_t</td> 2314 * <td>\c MTAPI_TRUE</td> 2315 * </tr> 2316 * <tr> 2317 * <td>\c MTAPI_QUEUE_RETAIN</td> 2318 * <td>Allow enqueuing of jobs when queue is disabled.</td> 2319 * <td>\c mtapi_boolean_t</td> 2320 * <td>\c MTAPI_FALSE</td> 2321 * </tr> 2322 * <tr> 2323 * <td>\c MTAPI_DOMAIN_SHARED</td> 2324 * <td>Indicates if the queue is shareable across domains.</td> 2325 * <td>\c mtapi_boolean_t</td> 2326 * <td>\c MTAPI_TRUE</td> 2327 * </tr> 2328 * </table> 2329 * 2330 * On success, \c *status is set to \c MTAPI_SUCCESS. On error, \c *status is 2331 * set to the appropriate error defined below. 2332 * Error code | Description 2333 * -------------------------- | ----------------------------------------------- 2334 * \c MTAPI_ERR_ATTR_READONLY | Attribute cannot be modified. 2335 * \c MTAPI_ERR_PARAMETER | Invalid attribute parameter. 2336 * \c MTAPI_ERR_ATTR_NUM | Unknown attribute number. 2337 * \c MTAPI_ERR_ATTR_SIZE | Incorrect attribute size. 2338 * \c MTAPI_ERR_NODE_NOTINIT | The calling node is not initialized. 2339 * 2340 * \see mtapi_queue_create(), mtapi_queueattr_init() 2341 * 2342 * \notthreadsafe 2343 * \memberof mtapi_queue_attributes_struct 2344 */ 2345 void mtapi_queueattr_set( 2346 MTAPI_INOUT mtapi_queue_attributes_t* attributes, 2347 /**< [in,out] Pointer to attributes */ 2348 MTAPI_IN mtapi_uint_t attribute_num, /**< [in] Attribute id */ 2349 MTAPI_IN void* attribute, /**< [in] Pointer to attribute value */ 2350 MTAPI_IN mtapi_size_t attribute_size, 2351 /**< [in] Size of attribute value. may 2352 be 0, attribute is interpreted as 2353 value in that case */ 2354 MTAPI_OUT mtapi_status_t* status /**< [out] Pointer to error code, 2355 may be \c MTAPI_NULL */ 2356 ); 2357 2358 /** 2359 * This function creates a software queue object and associates it with the 2360 * specified job. 2361 * 2362 * A job is associated with one or more actions that provide the executable 2363 * implementation of the job. Hardware queues are considered to be pre-existent 2364 * and do not need to be created. 2365 * 2366 * \c queue_id is an identifier of implementation-defined type that must be 2367 * supplied by the application. If \c queue_id is set to 2368 * \c MTAPI_QUEUE_ID_NONE, the queue will be accessible only on the node on 2369 * which it was created by using the returned queue handle. Otherwise the 2370 * application may supply a \c queue_id by which the queue can be referenced 2371 * domain-wide using mtapi_queue_get() to convert the id into a handle. The 2372 * minimum and maximum values for \c queue_id may be derived from 2373 * \c MTAPI_MIN_USER_QUEUE_ID and \c MTAPI_MAX_USER_QUEUE_ID. 2374 * 2375 * job is a handle to a job obtained by a previous call to mtapi_job_get(). If 2376 * \c attributes is \c MTAPI_NULL, the queue will be created with default 2377 * attribute values. Otherwise \c attributes must point to a queue attributes 2378 * object previously prepared using mtapi_queueattr_init() and 2379 * mtapi_queueattr_set(). 2380 * 2381 * There is an implementation-defined maximum number of queues permitted. 2382 * 2383 * If more than one action is associated with the job, the runtime system 2384 * chooses dynamically which action is used for execution (for load balancing 2385 * purposes). 2386 * 2387 * On success, a queue handle is returned and \c *status is set to 2388 * \c MTAPI_SUCCESS. On error, \c *status is set to the appropriate error 2389 * defined below. In the case where the queue already exists, \c *status will 2390 * be set to \c MTAPI_QUEUE_EXISTS and the handle returned will not be a 2391 * valid handle. 2392 * Error code | Description 2393 * -------------------------- | ----------------------------------------------- 2394 * \c MTAPI_ERR_QUEUE_INVALID | The \c queue_id is not a valid queue id. 2395 * \c MTAPI_ERR_QUEUE_EXISTS | This queue is already created. 2396 * \c MTAPI_ERR_QUEUE_LIMIT | Exceeded maximum number of queues allowed. 2397 * \c MTAPI_ERR_NODE_NOTINIT | The calling node is not initialized. 2398 * \c MTAPI_ERR_PARAMETER | Invalid attributes parameter. 2399 * \c MTAPI_ERR_JOB_INVALID | The associated job is not valid. 2400 * 2401 * \see mtapi_queue_get(), mtapi_job_get(), mtapi_queueattr_init(), 2402 * mtapi_queueattr_set() 2403 * 2404 * \returns Handle to newly created queue, invalid handle on error 2405 * \threadsafe 2406 * \ingroup QUEUES 2407 */ 2408 mtapi_queue_hndl_t mtapi_queue_create( 2409 MTAPI_IN mtapi_queue_id_t queue_id, /**< [in] Queue id */ 2410 MTAPI_IN mtapi_job_hndl_t job, /**< [in] Job handle */ 2411 MTAPI_IN mtapi_queue_attributes_t* attributes, 2412 /**< [in] Pointer to attributes */ 2413 MTAPI_OUT mtapi_status_t* status /**< [out] Pointer to error code, 2414 may be \c MTAPI_NULL */ 2415 ); 2416 2417 /** 2418 * Changes the attribute value that corresponds to the given \c attribute_num 2419 * for the specified queue. 2420 * 2421 * See mtapi_queueattr_set() for a list of predefined attribute numbers and 2422 * the sizes of the attribute values. The application must set 2423 * \c attribute_size to the exact size in bytes of the attribute value. 2424 * Additional attributes may be defined by the implementation. 2425 * 2426 * On success, \c *status is set to \c MTAPI_SUCCESS. On error, \c *status is 2427 * set to the appropriate error defined below and the attribute value is 2428 * undefined. 2429 * Error code | Description 2430 * -------------------------- | ----------------------------------------------- 2431 * \c MTAPI_ERR_PARAMETER | Invalid attribute parameter. 2432 * \c MTAPI_ERR_QUEUE_INVALID | Argument is not a valid queue handle. 2433 * \c MTAPI_ERR_ATTR_NUM | Unknown attribute number. 2434 * \c MTAPI_ERR_ATTR_SIZE | Incorrect attribute size. 2435 * \c MTAPI_ERR_NODE_NOTINIT | The calling node is not initialized. 2436 * 2437 * \see mtapi_queueattr_set() 2438 * 2439 * \notthreadsafe 2440 * \ingroup QUEUES 2441 */ 2442 void mtapi_queue_set_attribute( 2443 MTAPI_IN mtapi_queue_hndl_t queue, /**< [in] Queue handle */ 2444 MTAPI_IN mtapi_uint_t attribute_num, /**< [in] Attribute id */ 2445 MTAPI_IN void* attribute, /**< [in] Pointer to attribute value */ 2446 MTAPI_IN mtapi_size_t attribute_size, 2447 /**< [in] Size of attribute value. may 2448 be 0, attribute is interpreted as 2449 value in that case */ 2450 MTAPI_OUT mtapi_status_t* status /**< [out] Pointer to error code, 2451 may be \c MTAPI_NULL */ 2452 ); 2453 2454 /** 2455 * Returns the attribute value that corresponds to the given \c attribute_num 2456 * for the specified queue. 2457 * 2458 * \c attribute must point to a location in memory sufficiently large to hold 2459 * the returned attribute value. See mtapi_queueattr_set() for a list of 2460 * predefined attribute numbers and the sizes of the attribute values. The 2461 * application must set \c attribute_size to the exact size in bytes of the 2462 * attribute value. Additional attributes may be defined by the implementation. 2463 * 2464 * On success, \c *status is set to \c MTAPI_SUCCESS and the attribute value is 2465 * returned in \c *attribute. On error, \c *status is set to the appropriate 2466 * error defined below and the \c *attribute value is undefined. If this 2467 * function is called on a queue that no longer exists, an 2468 * \c MTAPI_ERR_QUEUE_INVALID error will be returned. 2469 * Error code | Description 2470 * -------------------------- | ----------------------------------------------- 2471 * \c MTAPI_ERR_PARAMETER | Invalid attribute parameter. 2472 * \c MTAPI_ERR_QUEUE_INVALID | Argument is not a valid queue handle. 2473 * \c MTAPI_ERR_ATTR_NUM | Unknown attribute number. 2474 * \c MTAPI_ERR_ATTR_SIZE | Incorrect attribute size. 2475 * \c MTAPI_ERR_NODE_NOTINIT | The calling node is not initialized. 2476 * 2477 * \see mtapi_queueattr_set() 2478 * 2479 * \waitfree 2480 * \ingroup QUEUES 2481 */ 2482 void mtapi_queue_get_attribute( 2483 MTAPI_IN mtapi_queue_hndl_t queue, /**< [in] Queue handle */ 2484 MTAPI_IN mtapi_uint_t attribute_num, /**< [in] Attribute id */ 2485 MTAPI_OUT void* attribute, /**< [out] Pointer to attribute value */ 2486 MTAPI_IN mtapi_size_t attribute_size,/**< [in] Size of attribute value */ 2487 MTAPI_OUT mtapi_status_t* status /**< [out] Pointer to error code, 2488 may be \c MTAPI_NULL */ 2489 ); 2490 2491 /** 2492 * This function converts a domain-wide \c queue_id into a node-local queue 2493 * handle. 2494 * 2495 * \c queue_id must match the \c queue_id that was associated with a software 2496 * queue that was created with mtapi_queue_create(), or it must be a valid 2497 * predefined queue identifier known a priori to the runtime and application 2498 * (e.g., to reference a hardware queue. The minimum and maximum values for 2499 * \c queue_id may be derived from \c MTAPI_MIN_USER_QUEUE_ID and 2500 * \c MTAPI_MAX_USER_QUEUE_ID. 2501 * 2502 * On success, the queue handle is returned and \c *status is set to 2503 * \c MTAPI_SUCCESS. On error, \c *status is set to the appropriate error 2504 * defined below. If this function is called on a queue that no longer exists, 2505 * an \c MTAPI_ERR_QUEUE_INVALID error will be returned. 2506 * <table> 2507 * <tr> 2508 * <th>Error code</th> 2509 * <th>Description</th> 2510 * </tr> 2511 * <tr> 2512 * <td>\c MTAPI_ERR_QUEUE_INVALID</td> 2513 * <td>The \c queue_id parameter does not refer to a valid queue or it is set 2514 * to \c MTAPI_QUEUE_ID_ANY.</td> 2515 * </tr> 2516 * <tr> 2517 * <td>\c MTAPI_ERR_NODE_NOTINIT</td> 2518 * <td>The node/domain is not initialized.</td> 2519 * </tr> 2520 * <tr> 2521 * <td>\c MTAPI_ERR_DOMAIN_NOTSHARED</td> 2522 * <td>This resource cannot be shared by this domain.</td> 2523 * </tr> 2524 * </table> 2525 * 2526 * \see mtapi_queue_create() 2527 * 2528 * \returns Handle to preexisting queue with given \c queue_id, 2529 * invalid handle on error 2530 * \threadsafe 2531 * \ingroup QUEUES 2532 */ 2533 mtapi_queue_hndl_t mtapi_queue_get( 2534 MTAPI_IN mtapi_queue_id_t queue_id, /**< [in] Queue id */ 2535 MTAPI_IN mtapi_domain_t domain_id, /**< [in] Domain id */ 2536 MTAPI_OUT mtapi_status_t* status /**< [out] Pointer to error code, 2537 may be \c MTAPI_NULL */ 2538 ); 2539 2540 /** 2541 * This function deletes the specified software queue. 2542 * 2543 * Hardware queues are perpetual and cannot be deleted. 2544 * 2545 * \c queue must be a valid handle to an existing queue. 2546 * 2547 * \c timeout determines how long the function should wait for tasks already 2548 * started via that queue to finish. The underlying type of \c mtapi_timeout_t 2549 * is implementation-defined. If \c timeout is a constant 0 or the symbolic 2550 * constant \c MTAPI_NOWAIT, this function deletes the queue and returns 2551 * immediately. If \c timeout is set to \c MTAPI_INFINITE the function may 2552 * block infinitely. Other values for \c timeout and the units of measure are 2553 * implementation defined. 2554 * 2555 * This function can be called from any node that has a valid queue handle. 2556 * Tasks previously enqueued in a queue that has been deleted may still be 2557 * executed depending on their internal state: 2558 * - If mtapi_queue_delete() is called on a queue that is currently executing 2559 * an action, the task state of the corresponding task will be set to 2560 * \c MTAPI_TASK_CANCELLED and execution will continue. To accomplish this, 2561 * the action function must poll the task state with 2562 * mtapi_context_taskstate_get(). A call to mtapi_task_wait() on the task 2563 * executing this code will return the status set by 2564 * mtapi_context_status_set(), or \c MTAPI_SUCCESS if not explicitly set. 2565 * - Tasks that are enqueued and waiting for execution by the MTAPI runtime 2566 * environment when mtapi_queue_delete() is called will not be executed any 2567 * more. A call to mtapi_task_wait() will return the status 2568 * \c MTAPI_ERR_QUEUE_DELETED. 2569 * - Tasks that are enqueued after deletion of the queue will return a status 2570 * of \c MTAPI_ERR_QUEUE_INVALID. 2571 * 2572 * If this function is called on a queue that no longer exists, an 2573 * \c MTAPI_ERR_QUEUE_INVALID status will be returned. A call to 2574 * mtapi_queue_get() on a deleted queue will return \c MTAPI_ERR_QUEUE_INVALID 2575 * as well, as long as no new queue has been created for the same queue ID. 2576 * 2577 * On success, \c *status is set to \c MTAPI_SUCCESS. On error, \c *status is 2578 * set to the appropriate error defined below. 2579 * Error code | Description 2580 * -------------------------- | ----------------------------------------------- 2581 * \c MTAPI_ERR_QUEUE_INVALID | Argument is not a valid queue handle. 2582 * \c MTAPI_ERR_NODE_NOTINIT | The calling node is not initialized. 2583 * \c MTAPI_TIMEOUT | Timeout was reached. 2584 * 2585 * \see mtapi_context_taskstate_get(), mtapi_context_status_set(), 2586 * mtapi_task_wait(), mtapi_queue_get() 2587 * 2588 * \threadsafe 2589 * \ingroup QUEUES 2590 */ 2591 void mtapi_queue_delete( 2592 MTAPI_IN mtapi_queue_hndl_t queue, /**< [in] Queue handle */ 2593 MTAPI_IN mtapi_timeout_t timeout, /**< [in] Timeout duration in 2594 milliseconds */ 2595 MTAPI_OUT mtapi_status_t* status /**< [out] Pointer to error code, 2596 may be \c MTAPI_NULL */ 2597 ); 2598 2599 /** 2600 * This function disables the specified queue in such a way that it can be 2601 * resumed later. 2602 * 2603 * This is needed to perform certain maintenance tasks. It can be called by 2604 * any node that has a valid queue handle. 2605 * 2606 * \c timeout determines how long the function should wait for tasks already 2607 * started via that queue to finish. The underlying type of \c mtapi_timeout_t 2608 * is implementation-defined. If \c timeout is a constant 0 or the symbolic 2609 * constant \c MTAPI_NOWAIT, this function deletes the queue and returns 2610 * immediately. If \c timeout is set to \c MTAPI_INFINITE the function may 2611 * block infinitely. Other values for \c timeout and the units of measure are 2612 * implementation defined. 2613 * 2614 * Tasks previously enqueued in a queue that has been disabled may still be 2615 * executed depending on their internal state: 2616 * - If mtapi_queue_disable() is called on a queue that is currently executing 2617 * an action, the task state of the corresponding task will be set to 2618 * \c MTAPI_TASK_CANCELLED and execution will continue. To accomplish this, 2619 * the action function must poll the task state by calling 2620 * mtapi_context_taskstate_get(). A call to mtapi_task_wait() on the task 2621 * executing this code will return the status set by 2622 * mtapi_context_status_set(), or \c MTAPI_SUCCESS if not explicitly set. 2623 * - Tasks that are enqueued and waiting for execution by the MTAPI runtime 2624 * environment when mtapi_queue_disable() is called will not be executed 2625 * anymore. They will be held in anticipation the queue is enabled again 2626 * if the \c MTAPI_QUEUE_RETAIN attribute is set to \c MTAPI_TRUE. A call to 2627 * mtapi_task_wait() will return the status \c MTAPI_ERR_QUEUE_DISABLED. 2628 * - Tasks that are enqueued after the queue had been disabled will return 2629 * \c MTAPI_ERR_QUEUE_DISABLED if the \c MTAPI_QUEUE_RETAIN attribute is set 2630 * to \c MTAPI_FALSE. 2631 * 2632 * On success, \c *status is set to \c MTAPI_SUCCESS. On error, \c *status is 2633 * set to the appropriate error defined below. 2634 * Error code | Description 2635 * -------------------------- | ----------------------------------------------- 2636 * \c MTAPI_ERR_QUEUE_INVALID | Argument is not a valid queue handle. 2637 * \c MTAPI_ERR_NODE_NOTINIT | The calling node is not initialized. 2638 * \c MTAPI_TIMEOUT | Timeout was reached. 2639 * 2640 * \see mtapi_context_taskstate_get(), mtapi_context_status_set(), 2641 * mtapi_task_wait() 2642 * 2643 * \threadsafe 2644 * \ingroup QUEUES 2645 */ 2646 void mtapi_queue_disable( 2647 MTAPI_IN mtapi_queue_hndl_t queue, /**< [in] Queue handle */ 2648 MTAPI_IN mtapi_timeout_t timeout, /**< [in] Timeout duration in 2649 milliseconds */ 2650 MTAPI_OUT mtapi_status_t* status /**< [out] Pointer to error code, 2651 may be \c MTAPI_NULL */ 2652 ); 2653 2654 /** 2655 * This function may be called from any node with a valid queue handle to 2656 * re-enable a queue previously disabled with mtapi_queue_disable(). 2657 * 2658 * On success, \c *status is set to \c MTAPI_SUCCESS. On error, \c *status is 2659 * set to the appropriate error defined below. 2660 * Error code | Description 2661 * -------------------------- | ----------------------------------------------- 2662 * \c MTAPI_ERR_QUEUE_INVALID | Argument is not a valid queue handle. 2663 * \c MTAPI_ERR_NODE_NOTINIT | The calling node is not initialized. 2664 * 2665 * \threadsafe 2666 * \ingroup QUEUES 2667 */ 2668 void mtapi_queue_enable( 2669 MTAPI_IN mtapi_queue_hndl_t queue, /**< [in] Queue handle */ 2670 MTAPI_OUT mtapi_status_t* status /**< [out] Pointer to error code, 2671 may be \c MTAPI_NULL */ 2672 ); 2673 2674 2675 /* ---- JOBS --------------------------------------------------------------- */ 2676 2677 /** 2678 * \defgroup JOBS Jobs 2679 * 2680 * \ingroup C_MTAPI 2681 * 2682 * Jobs implementing one or more actions. 2683 * 2684 * An action is a hardware or software implementation of a job. In some cases, 2685 * an action is referenced by an action handle, while in other cases, an action 2686 * is referenced indirectly through a job handle. Each job is represented by a 2687 * domain-wide job ID, or by a job handle which is local to one node. 2688 * 2689 * Several actions can implement the same job based on different hardware 2690 * resources (for instance a job can be implemented by one action on a DSP and 2691 * by another action on a general purpose core, or a job can be implemented by 2692 * both hardware and software actions). 2693 */ 2694 2695 /** 2696 * Given a \c job_id, this function returns the MTAPI handle for referencing 2697 * the actions implementing the job. 2698 * 2699 * This function converts a domain-wide job ID into a node-local job handle. 2700 * 2701 * On success, the action handle is returned and \c *status is set to 2702 * \c MTAPI_SUCCESS. On error, \c *status is set to the appropriate error 2703 * defined below. 2704 * Error code | Description 2705 * ----------------------------- | -------------------------------------------- 2706 * \c MTAPI_ERR_JOB_INVALID | The job ID does not refer to a valid action. 2707 * \c MTAPI_ERR_DOMAIN_NOTSHARED | The resource can't be shared by this domain. 2708 * \c MTAPI_ERR_NODE_NOTINIT | The calling node is not initialized. 2709 * 2710 * \returns Handle to job with given \c job_id, invalid handle on error 2711 * \threadsafe 2712 * \ingroup JOBS 2713 */ 2714 mtapi_job_hndl_t mtapi_job_get( 2715 MTAPI_IN mtapi_job_id_t job_id, /**< [in] Job id */ 2716 MTAPI_IN mtapi_domain_t domain_id, /**< [in] Domain id */ 2717 MTAPI_OUT mtapi_status_t* status /**< [out] Pointer to error code, 2718 may be \c MTAPI_NULL */ 2719 ); 2720 2721 2722 /* ---- TASKS -------------------------------------------------------------- */ 2723 2724 /** 2725 * \defgroup TASKS Tasks 2726 * 2727 * \ingroup C_MTAPI 2728 * 2729 * Tasks representing pieces of work "in flight" (similar to a thread handles). 2730 * 2731 * A task is associated with a job object, which is associated with one or 2732 * more actions implementing the same job for load balancing purposes. 2733 * A task may optionally be associated with a task group. A task has 2734 * attributes, and an internal state. A task begins its lifetime with a call 2735 * to mtapi_task_start() or mtapi_task_enqueue(). A 2736 * task is referenced by a handle of type \c mtapi_task_hndl_t. The underlying 2737 * type of \c mtapi_task_hndl_t is implementation defined. Task handles may be 2738 * copied, assigned, and passed as arguments, but otherwise the application 2739 * should make no assumptions about the internal representation of a task 2740 * handle. 2741 * 2742 * Once a task is started, it is possible to wait for task completion from 2743 * other parts of the program. 2744 */ 2745 2746 /** 2747 * This function initializes a task attributes object. 2748 * 2749 * A task attributes object is a container of task attributes. It is an 2750 * optional argument passed to mtapi_task_start() or mtapi_task_enqueue() to 2751 * specify non-default task attributes when starting a task. 2752 * 2753 * To set task attributes to non-default values, the application must allocate 2754 * a task attributes object of type \c mtapi_task_attributes_t and initialize 2755 * it with a call to mtapi_taskattr_init(). The application may call 2756 * mtapi_taskattr_set() to specify attribute values. Calls to 2757 * mtapi_taskattr_init() have no effect on task attributes after the task has 2758 * started. The \c mtapi_task_attributes_t object may safely be deleted by the 2759 * application after the task has started. 2760 * 2761 * On success, \c *status is set to \c MTAPI_SUCCESS. On error, \c *status is 2762 * set to the appropriate error defined below. 2763 * Error code | Description 2764 * ------------------------- | ------------------------------------------------ 2765 * \c MTAPI_ERR_PARAMETER | Invalid attributes parameter. 2766 * \c MTAPI_ERR_NODE_NOTINIT | The calling node is not initialized. 2767 * 2768 * \see mtapi_task_start(), mtapi_task_enqueue(), mtapi_taskattr_set() 2769 * 2770 * \notthreadsafe 2771 * \memberof mtapi_task_attributes_struct 2772 */ 2773 void mtapi_taskattr_init( 2774 MTAPI_OUT mtapi_task_attributes_t* attributes, 2775 /**< [out] Pointer to attributes */ 2776 MTAPI_OUT mtapi_status_t* status /**< [out] Pointer to error code, 2777 may be \c MTAPI_NULL */ 2778 ); 2779 2780 /** 2781 * This function sets task attribute values in a task attributes object. 2782 * 2783 * A task attributes object is a container of task attributes, optionally 2784 * passed to mtapi_task_start() or mtapi_task_enqueue() to specify non-default 2785 * task attributes when starting a task. 2786 * 2787 * attributes is a pointer to a task attributes object that was previously 2788 * initialized with a call to mtapi_taskattr_init(). Calls to 2789 * mtapi_taskattr_set() have no effect on task attributes after the task has 2790 * been created. The task attributes object may safely be deleted by the 2791 * application after the task has started. 2792 * 2793 * See the table below for a list of predefined attribute numbers and the 2794 * sizes of the attribute values. The application must set attribute_size to 2795 * the exact size in bytes of the attribute value. Additional attributes may 2796 * be defined by the implementation. 2797 * 2798 * MTAPI-defined task attributes: 2799 * <table> 2800 * <tr> 2801 * <th>Attribute num</th> 2802 * <th>Description</th> 2803 * <th>Data Type</th> 2804 * <th>Default</th> 2805 * </tr> 2806 * <tr> 2807 * <td>\c MTAPI_TASK_DETACHED</td> 2808 * <td>Indicates if this is a detached task. A detached task is deleted by 2809 * MTAPI runtime after execution. The task handle of detached tasks 2810 * must not be used, i.e., it is not possible to wait for completion 2811 * of dedicated detached tasks. But it is possible to add detached 2812 * tasks to a group and wait for completion of the group.</td> 2813 * <td>\c mtapi_boolean_t</td> 2814 * <td>\c MTAPI_FALSE</td> 2815 * </tr> 2816 * <tr> 2817 * <td>\c MTAPI_TASK_INSTANCES</td> 2818 * <td>Indicates how many parallel instances of task shall be started by 2819 * MTAPI. The default case is that each task is executed exactly once. 2820 * Setting this value to n, the corresponding action code will be 2821 * executed n times, in parallel, if the underlying hardware allows it. 2822 * (see chapter 4.1.7 Multi-Instance Tasks, page 107)</td> 2823 * <td>\c mtapi_uint_t</td> 2824 * <td>1</td> 2825 * </tr> 2826 * <tr> 2827 * <td>\c MTAPI_TASK_PRIORITY</td> 2828 * <td>Indicates the prority this task should be run at. Priorities range 2829 * from zero to one minus the maximum number of priorities specified at 2830 * the call to mtapi_initialize().</td> 2831 * <td>\c mtapi_uint_t</td> 2832 * <td>0 (default priority)</td> 2833 * </tr> 2834 * <tr> 2835 * <td>\c MTAPI_TASK_AFFINITY</td> 2836 * <td>Indicates the affinity of this task. Affinities are manipulated by 2837 * the matpi_affinity_init() and mtapi_affinity_set() calls.</td> 2838 * <td>\c mtapi_affinity_t</td> 2839 * <td>all workers</td> 2840 * </tr> 2841 * <tr> 2842 * <td>\c MTAPI_TASK_USER_DATA</td> 2843 * <td>Provides a pointer to some data required by the user during scheduling 2844 * (e.g. in a MTAPI plugin).</td> 2845 * <td>\c void*</td> 2846 * <td>\c MTAPI_NULL</td> 2847 * </tr> 2848 * <tr> 2849 * <td>\c MTAPI_TASK_COMPLETE_FUNCTION</td> 2850 * <td>Pointer to a function being called when the task finishes.</td> 2851 * <td>\c mtapi_task_complete_function_t</td> 2852 * <td>\c MTAPI_NULL</td> 2853 * </tr> 2854 * </table> 2855 * 2856 * On success, \c *status is set to \c MTAPI_SUCCESS. On error, \c *status is 2857 * set to the appropriate error defined below. 2858 * Error code | Description 2859 * -------------------------- | ----------------------------------------------- 2860 * \c MTAPI_ERR_ATTR_READONLY | Attribute cannot be modified. 2861 * \c MTAPI_ERR_PARAMETER | Invalid attribute parameter. 2862 * \c MTAPI_ERR_ATTR_NUM | Unknown attribute number. 2863 * \c MTAPI_ERR_ATTR_SIZE | Incorrect attribute size. 2864 * \c MTAPI_ERR_NODE_NOTINIT | The calling node is not initialized. 2865 * 2866 * \see mtapi_task_start(), mtapi_task_enqueue(), mtapi_taskattr_init() 2867 * 2868 * \notthreadsafe 2869 * \memberof mtapi_task_attributes_struct 2870 */ 2871 void mtapi_taskattr_set( 2872 MTAPI_INOUT mtapi_task_attributes_t* attributes, 2873 /**< [in, out] Pointer to attributes */ 2874 MTAPI_IN mtapi_uint_t attribute_num, /**< [in] Attribute id */ 2875 MTAPI_IN void* attribute, /**< [in] Pointer to attribute value */ 2876 MTAPI_IN mtapi_size_t attribute_size, 2877 /**< [in] Size of attribute value. may 2878 be 0, attribute is interpreted as 2879 value in that case */ 2880 MTAPI_OUT mtapi_status_t* status /**< [out] Pointer to error code, 2881 may be \c MTAPI_NULL */ 2882 ); 2883 2884 /** 2885 * This function schedules a task for execution. 2886 * 2887 * A task is associated with a job. A job is associated with one or more 2888 * actions. An action provides an action function, which is the executable 2889 * implementation of a job. If more than one action is associated with the job, 2890 * the runtime system chooses dynamically which action is used for execution 2891 * for load balancing purposes. 2892 * 2893 * \c task_id is an optional ID provided by the application for debugging 2894 * purposes. If not needed, it can be set to \c MTAPI_TASK_ID_NONE. The minimum 2895 * and maximum values for \c task_id may be derived from 2896 * \c MTAPI_MIN_USER_TASK_ID and \c MTAPI_MAX_USER_TASK_ID. 2897 * 2898 * \c job must be a handle to a job obtained by a previous call to 2899 * mtapi_job_get(). 2900 * 2901 * If \c arguments_size is not zero, then arguments must point to data of 2902 * \c arguments_size bytes. The arguments will be transferred by the runtime 2903 * from the node where the action was created to the executing node if 2904 * necessary. Marshalling of arguments is not part of the MTAPI specification 2905 * and is implementation-defined. 2906 * 2907 * If \c attributes is \c MTAPI_NULL, the task will be started with default 2908 * attribute values. Otherwise \c attributes must point to a task attributes 2909 * object previously prepared using mtapi_taskattr_init() and 2910 * mtapi_taskattr_set(). The attributes of a task cannot be changed after the 2911 * task is created. 2912 * 2913 * \c group must be set to \c MTAPI_GROUP_NONE if the task is not part of a 2914 * task group. Otherwise \c group must be a group handle obtained by a previous 2915 * call to mtapi_group_create(). 2916 * 2917 * On success, a task handle is returned and \c *status is set to 2918 * \c MTAPI_SUCCESS. On error, \c *status is set to the appropriate error 2919 * defined below. 2920 * Error code | Description 2921 * -------------------------- | ----------------------------------------------- 2922 * \c MTAPI_ERR_TASK_LIMIT | Exceeded maximum number of tasks allowed. 2923 * \c MTAPI_ERR_NODE_NOTINIT | The calling node is not initialized. 2924 * \c MTAPI_ERR_PARAMETER | Invalid attributes parameter. 2925 * \c MTAPI_ERR_GROUP_INVALID | Argument is not a valid group handle. 2926 * \c MTAPI_ERR_JOB_INVALID | The associated job is not valid. 2927 * 2928 * \see mtapi_job_get(), mtapi_taskattr_init(), mtapi_taskattr_set(), 2929 * mtapi_group_create() 2930 * 2931 * \returns Handle to newly started task, invalid handle on error 2932 * \threadsafe 2933 * \ingroup TASKS 2934 */ 2935 mtapi_task_hndl_t mtapi_task_start( 2936 MTAPI_IN mtapi_task_id_t task_id, /**< [in] Task id */ 2937 MTAPI_IN mtapi_job_hndl_t job, /**< [in] Job handle */ 2938 MTAPI_IN void* arguments, /**< [in] Pointer to arguments */ 2939 MTAPI_IN mtapi_size_t arguments_size,/**< [in] Size of arguments */ 2940 MTAPI_OUT void* result_buffer, /**< [out] Pointer to result buffer */ 2941 MTAPI_IN mtapi_size_t result_size, /**< [in] Size of one result */ 2942 MTAPI_IN mtapi_task_attributes_t* attributes, 2943 /**< [in] Pointer to attributes */ 2944 MTAPI_IN mtapi_group_hndl_t group, /**< [in] Group handle, may be 2945 \c MTAPI_GROUP_NONE */ 2946 MTAPI_OUT mtapi_status_t* status /**< [out] Pointer to error code, 2947 may be \c MTAPI_NULL */ 2948 ); 2949 2950 /** 2951 * This function schedules a task for execution using a queue. 2952 * 2953 * A queue is a task associated with a job. A job is associated with one or 2954 * more actions. An action provides an action function, which is the executable 2955 * implementation of a job. 2956 * 2957 * \c task_id is an optional ID provided by the application for debugging 2958 * purposes. If not needed, it can be set to \c MTAPI_TASK_ID_NONE. The 2959 * underlying type of \c mtapi_task_id_t is implementation-defined. The 2960 * minimum and maximum values for \c task_id may be derived from 2961 * \c MTAPI_MIN_USER_TASK_ID and \c MTAPI_MAX_USER_TASK_ID. 2962 * 2963 * \c queue must be a handle to a queue obtained by a previous call to 2964 * mtapi_queue_create(). 2965 * 2966 * If \c arguments_size is not zero, then arguments must point to data of 2967 * \c arguments_size bytes. The arguments will be transferred by the runtime 2968 * from the node where the action was created to the executing node. 2969 * Marshalling of arguments is not part of the MTAPI specification and is 2970 * implementation-defined. 2971 * 2972 * If \c attributes is \c MTAPI_NULL, the task will be started with default 2973 * attribute values. Otherwise \c attributes must point to a task attributes 2974 * object previously prepared using mtapi_taskattr_init() and 2975 * mtapi_taskattr_set(). Once a task has been enqueued, its attributes may not 2976 * be changed. 2977 * 2978 * \c group must be set to \c MTAPI_GROUP_NONE if the task is not part of a 2979 * task group. Otherwise \c group must be a group handle obtained by a 2980 * previous call to mtapi_group_create(). 2981 * 2982 * On success, a task handle is returned and \c *status is set to 2983 * \c MTAPI_SUCCESS. On error, \c *status is set to the appropriate error 2984 * defined below. 2985 * Error code | Description 2986 * -------------------------- | ----------------------------------------------- 2987 * \c MTAPI_ERR_TASK_LIMIT | Exceeded maximum number of tasks allowed. 2988 * \c MTAPI_ERR_NODE_NOTINIT | The calling node is not initialized. 2989 * \c MTAPI_ERR_PARAMETER | Invalid attributes parameter. 2990 * \c MTAPI_ERR_QUEUE_INVALID | Argument is not a valid queue handle. 2991 * 2992 * \see mtapi_queue_create(), mtapi_taskattr_init(), mtapi_taskattr_set(), 2993 * mtapi_group_create() 2994 * 2995 * \returns Handle to newly enqueued task, invalid handle on error 2996 * \threadsafe 2997 * \ingroup TASKS 2998 */ 2999 mtapi_task_hndl_t mtapi_task_enqueue( 3000 MTAPI_IN mtapi_task_id_t task_id, /**< [in] Task id */ 3001 MTAPI_IN mtapi_queue_hndl_t queue, /**< [in] Queue handle */ 3002 MTAPI_IN void* arguments, /**< [in] Pointer to arguments */ 3003 MTAPI_IN mtapi_size_t arguments_size,/**< [in] Size of arguments */ 3004 MTAPI_OUT void* result_buffer, /**< [out] Pointer to result buffer */ 3005 MTAPI_IN mtapi_size_t result_size, /**< [in] Size of one result */ 3006 MTAPI_IN mtapi_task_attributes_t* attributes, 3007 /**< [in] Pointer to task attributes */ 3008 MTAPI_IN mtapi_group_hndl_t group, /**< [in] Group handle, may be 3009 \c MTAPI_GROUP_NONE */ 3010 MTAPI_OUT mtapi_status_t* status /**< [out] Pointer to error code, 3011 may be \c MTAPI_NULL */ 3012 ); 3013 3014 /** 3015 * Returns a copy of the attribute value that corresponds to the given 3016 * \c attribute_num for the specified task. 3017 * 3018 * The attribute value will be returned in \c *attribute. Note that task 3019 * attributes may be queried but may not be changed after a task has been 3020 * created. 3021 * 3022 * \c task must be a valid handle to a task that was obtained by a previous 3023 * call to mtapi_task_start() or mtapi_task_enqueue(). 3024 * 3025 * See mtapi_taskattr_set() for a list of predefined attribute numbers 3026 * and the sizes of the attribute values. The application is responsible for 3027 * allocating sufficient space for the returned attribute value and for 3028 * setting \c attribute_size to the exact size in bytes of the attribute value. 3029 * 3030 * On success, \c *status is set to \c MTAPI_SUCCESS and the attribute value is 3031 * returned in \c *attribute. On error, \c *status is set to the appropriate 3032 * error defined below and the attribute value is undefined. If this function 3033 * is called on a task that no longer exists, an \c MTAPI_ERR_TASK_INVALID 3034 * error code will be returned. 3035 * Error code | Description 3036 * ------------------------- | ------------------------------------------------ 3037 * \c MTAPI_ERR_PARAMETER | Invalid attribute parameter. 3038 * \c MTAPI_ERR_TASK_INVALID | Argument is not a valid task handle. 3039 * \c MTAPI_ERR_ATTR_NUM | Unknown attribute number. 3040 * \c MTAPI_ERR_ATTR_SIZE | Incorrect attribute size. 3041 * \c MTAPI_ERR_NODE_NOTINIT | The calling node is not initialized. 3042 * 3043 * \see mtapi_task_start(), mtapi_task_enqueue(), mtapi_taskattr_set() 3044 * 3045 * \waitfree 3046 * \ingroup TASKS 3047 */ 3048 void mtapi_task_get_attribute( 3049 MTAPI_IN mtapi_task_hndl_t task, /**< [in] Task handle */ 3050 MTAPI_IN mtapi_uint_t attribute_num, /**< [in] Attribute id */ 3051 MTAPI_OUT void* attribute, /**< [out] Pointer to attribute value */ 3052 MTAPI_IN mtapi_size_t attribute_size,/**< [in] Size of attribute value */ 3053 MTAPI_OUT mtapi_status_t* status /**< [out] Pointer to error code, 3054 may be \c MTAPI_NULL */ 3055 ); 3056 3057 /** 3058 * This function cancels a task and sets the task status to 3059 * \c MTAPI_TASK_CANCELLED. 3060 * 3061 * \c task must be a valid handle to a task that was obtained by a previous 3062 * call to mtapi_task_start() or mtapi_task_enqueue(). 3063 * 3064 * If the execution of a task has not been started, the runtime system might 3065 * remove the task from the runtime-internal task queues. If task execution is 3066 * already running, an action function implemented in software can poll the 3067 * task status and react accordingly. 3068 * 3069 * Since the task is referenced by a task handle which can only be used 3070 * node-locally, a task can be canceled only on the node where the task was 3071 * created. 3072 * 3073 * On success, \c *status is set to \c MTAPI_SUCCESS. On error, \c *status is 3074 * set to the appropriate error defined below. 3075 * Error code | Description 3076 * ------------------------- | ------------------------------------------------ 3077 * \c MTAPI_ERR_TASK_INVALID | Argument is not a valid task handle. 3078 * \c MTAPI_ERR_NODE_NOTINIT | The calling node is not initialized. 3079 * 3080 * \see mtapi_task_start(), mtapi_task_enqueue() 3081 * 3082 * \waitfree 3083 * \ingroup TASKS 3084 */ 3085 void mtapi_task_cancel( 3086 MTAPI_IN mtapi_task_hndl_t task, /**< [in] Task handle */ 3087 MTAPI_OUT mtapi_status_t* status /**< [out] Pointer to error code, 3088 may be \c MTAPI_NULL */ 3089 ); 3090 3091 /** 3092 * This function waits for the completion of the specified task. 3093 * 3094 * \c task must be a valid handle to a task that was obtained by a previous 3095 * call to mtapi_task_start() or mtapi_task_enqueue(). The task handle becomes 3096 * invalid on a successful wait, i.e., after the task had run to completion 3097 * and mtapi_task_wait() returns \c MTAPI_SUCCESS. 3098 * 3099 * \c timeout determines how long the function should wait for tasks already 3100 * started via that queue to finish. The underlying type of \c mtapi_timeout_t 3101 * is implementation-defined. If \c timeout is a constant 0 or the symbolic 3102 * constant \c MTAPI_NOWAIT, this function does not block and returns 3103 * immediately. If \c timeout is set to \c MTAPI_INFINITE the function may 3104 * block infinitely. Other values for \c timeout and the units of measure are 3105 * implementation-defined. 3106 * 3107 * Results of completed tasks can be obtained via \c result_buffer associated 3108 * with the task. The size of the buffer has to be equal to the result size 3109 * written in the action code. If the result is not needed by the calling 3110 * code, \c result_buffer may be set to \c MTAPI_NULL. For multi-instance 3111 * tasks, the result buffer is filled by an array of all the task instances' 3112 * results. I.e., the result buffer has to be allocated big enough (number of 3113 * instances times size of result). 3114 * 3115 * Calling mtapi_task_wait() more than once for the same task results in 3116 * undefined behavior. 3117 * 3118 * On success, \c *status is set to \c MTAPI_SUCCESS. On error, \c *status is 3119 * set to the appropriate error defined below. If this function is called on 3120 * a task that no longer exists, an \c MTAPI_ERR_TASK_INVALID error code will 3121 * be returned. \c status will be \c MTAPI_ERR_ARG_SIZE or 3122 * \c MTAPI_ERR_RESULT_SIZE if the sizes of arguments or result buffer do 3123 * not match. 3124 * <table> 3125 * <tr> 3126 * <th>Error code</th> 3127 * <th>Description</th> 3128 * </tr> 3129 * <tr> 3130 * <td>\c MTAPI_ERR_TASK_INVALID</td> 3131 * <td>Argument is not a valid task handle.</td> 3132 * </tr> 3133 * <tr> 3134 * <td>\c MTAPI_TIMEOUT</td> 3135 * <td>Timeout was reached.</td> 3136 * </tr> 3137 * <tr> 3138 * <td>\c MTAPI_ERR_PARAMETER</td> 3139 * <td>Invalid timeout parameter.</td> 3140 * </tr> 3141 * <tr> 3142 * <td>\c MTAPI_ERR_TASK_CANCELLED</td> 3143 * <td>The task has been canceled because of mtapi_task_cancel() was 3144 * called before the task was executed or the error code was set to 3145 * \c MTAPI_ERR_TASK_CANCELLED by mtapi_context_status_set() in the 3146 * action function.</td> 3147 * </tr> 3148 * <tr> 3149 * <td>\c MTAPI_ERR_WAIT_PENDING</td> 3150 * <td>mtapi_task_wait() had already been called for the same task and the 3151 * first wait call is still pending.</td> 3152 * </tr> 3153 * <tr> 3154 * <td>\c MTAPI_ERR_ACTION_CANCELLED</td> 3155 * <td>Action execution was canceled by the action function 3156 * (mtapi_context_status_set()).</td> 3157 * </tr> 3158 * <tr> 3159 * <td>\c MTAPI_ERR_ACTION_FAILED</td> 3160 * <td>Error set by action function (mtapi_context_status_set()).</td> 3161 * </tr> 3162 * <tr> 3163 * <td>\c MTAPI_ERR_ACTION_DELETED</td> 3164 * <td>All actions associated with the task have been deleted before the 3165 * execution of the task was started or the error code has been set in 3166 * the action function to \c MTAPI_ERR_ACTION_DELETED by 3167 * mtapi_context_status_set().</td> 3168 * </tr> 3169 * <tr> 3170 * <td>\c MTAPI_ERR_ARG_SIZE</td> 3171 * <td>The size of the arguments expected by action differs from arguments 3172 * size of the caller.</td> 3173 * </tr> 3174 * <tr> 3175 * <td>\c MTAPI_ERR_RESULT_SIZE</td> 3176 * <td>The size of the result buffer expected by action differs from 3177 * result buffer size of the caller.</td> 3178 * </tr> 3179 * <tr> 3180 * <td>\c MTAPI_ERR_NODE_NOTINIT</td> 3181 * <td>The calling node is not initialized.</td> 3182 * </tr> 3183 * </table> 3184 * 3185 * \see mtapi_task_start(), mtapi_task_enqueue(), mtapi_task_wait(), 3186 * mtapi_task_cancel(), mtapi_context_status_set() 3187 * 3188 * \threadsafe 3189 * \ingroup TASKS 3190 */ 3191 void mtapi_task_wait( 3192 MTAPI_IN mtapi_task_hndl_t task, /**< [in] Task handle */ 3193 MTAPI_IN mtapi_timeout_t timeout, /**< [in] Timeout duration in 3194 milliseconds */ 3195 MTAPI_OUT mtapi_status_t* status /**< [out] Pointer to error code, 3196 may be \c MTAPI_NULL */ 3197 ); 3198 3199 3200 /* ---- TASK GROUPS -------------------------------------------------------- */ 3201 3202 /** 3203 * \defgroup TASK_GROUPS Task Groups 3204 * 3205 * \ingroup C_MTAPI 3206 * 3207 * Facilities for synchronizing on groups of tasks. 3208 * 3209 * This concept is similar to barrier synchronization of threads. MTAPI 3210 * specifies a minimal task group feature set in order to allow small and 3211 * efficient implementations. 3212 */ 3213 3214 /** 3215 * This function initializes a group attributes object. 3216 * 3217 * A group attributes object is a container of group attributes. It is an 3218 * optional argument passed to mtapi_group_create() to specify non-default 3219 * group attributes when creating a task group. 3220 * 3221 * To set group attributes to non-default values, the application must 3222 * allocate a group attributes object of type \c mtapi_group_attributes_t and 3223 * initialize it with a call to mtapi_groupattr_init(). The application may 3224 * call mtapi_groupattr_set() to specify attribute values. Calls to 3225 * mtapi_groupattr_init() have no effect on group attributes after the group 3226 * has been created. The \c mtapi_group_attributes_t object may safely be 3227 * deleted by the application after the call to mtapi_group_create(). 3228 * 3229 * On success, \c *status is set to \c MTAPI_SUCCESS. On error, \c *status is 3230 * set to the appropriate error defined below. 3231 * Error code | Description 3232 * ------------------------- | ------------------------------------------------ 3233 * \c MTAPI_ERR_PARAMETER | Invalid attributes parameter. 3234 * \c MTAPI_ERR_NODE_NOTINIT | The calling node is not initialized. 3235 * 3236 * \see mtapi_group_create(), mtapi_groupattr_set() 3237 * 3238 * \notthreadsafe 3239 * \memberof mtapi_group_attributes_struct 3240 */ 3241 void mtapi_groupattr_init( 3242 MTAPI_OUT mtapi_group_attributes_t* attributes, 3243 /**< [out] Pointer to attributes */ 3244 MTAPI_OUT mtapi_status_t* status /**< [out] Pointer to error code, 3245 may be \c MTAPI_NULL */ 3246 ); 3247 3248 /** 3249 * This function sets group attribute values in a group attributes object. 3250 * 3251 * A group attributes object is a container of group attributes, optionally 3252 * passed to mtapi_group_create() to specify non-default group attributes when 3253 * creating a task group. 3254 * 3255 * \c attributes is a pointer to a group attributes object that was previously 3256 * initialized with a call to mtapi_groupattr_init(). Calls to 3257 * mtapi_groupattr_set() have no effect on group attributes after the group 3258 * has been created. The group attributes object may safely be deleted by the 3259 * application after the call to mtapi_group_create(). 3260 * 3261 * See the table below for a list of predefined attribute numbers and the 3262 * sizes of the attribute values. The application must set \c attribute_size to 3263 * the exact size in bytes of the attribute value. 3264 * Additional attributes may be defined by the implementation. 3265 * 3266 * On success, \c *status is set to \c MTAPI_SUCCESS. On error, \c *status is 3267 * set to the appropriate error defined below. 3268 * Error code | Description 3269 * -------------------------- | ----------------------------------------------- 3270 * \c MTAPI_ERR_ATTR_READONLY | Attribute cannot be modified. 3271 * \c MTAPI_ERR_PARAMETER | Invalid attribute parameter. 3272 * \c MTAPI_ERR_ATTR_NUM | Unknown attribute number. 3273 * \c MTAPI_ERR_ATTR_SIZE | Incorrect attribute size. 3274 * \c MTAPI_ERR_NODE_NOTINIT | The calling node is not initialized. 3275 * 3276 * \see mtapi_group_create(), mtapi_groupattr_init() 3277 * 3278 * \notthreadsafe 3279 * \memberof mtapi_group_attributes_struct 3280 */ 3281 void mtapi_groupattr_set( 3282 MTAPI_INOUT mtapi_group_attributes_t* attributes, 3283 /**< [in,out] Pointer to attributes */ 3284 MTAPI_IN mtapi_uint_t attribute_num, /**< [in] Attribute id */ 3285 MTAPI_IN void* attribute, /**< [in] Pointer to attribute value */ 3286 MTAPI_IN mtapi_size_t attribute_size, 3287 /**< [in] Size of attribute value. may 3288 be 0, attribute is interpreted as 3289 value in that case */ 3290 MTAPI_OUT mtapi_status_t* status /**< [out] Pointer to error code, 3291 may be \c MTAPI_NULL */ 3292 ); 3293 3294 /** 3295 * This function creates a task group and returns a handle to the group. 3296 * 3297 * After a group is created, a task may be associated with a group when the 3298 * task is started with mtapi_task_start() or mtapi_task_enqueue(). 3299 * 3300 * \c group_id is an optional ID provided by the application for debugging 3301 * purposes. If not needed, it can be set to \c MTAPI_GROUP_ID_NONE. The 3302 * underlying type of \c mtapi_group_id_t is implementation-defined. The 3303 * minimum and maximum values for \c group_id may be derived from 3304 * \c MTAPI_MIN_USER_GROUP_ID and \c MTAPI_MAX_USER_GROUP_ID. 3305 * 3306 * If \c attributes is \c MTAPI_NULL, the group will be created with default 3307 * attribute values. Otherwise \c attributes must point to a group attributes 3308 * object previously prepared using mtapi_groupattr_init() and 3309 * mtapi_groupattr_set(). 3310 * 3311 * On success, a group handle is returned and \c *status is set to 3312 * \c MTAPI_SUCCESS. On error, \c *status is set to the appropriate error 3313 * defined below. 3314 * Error code | Description 3315 * ------------------------- | ------------------------------------------------ 3316 * \c MTAPI_ERR_GROUP_LIMIT | Exceeded maximum number of groups allowed. 3317 * \c MTAPI_ERR_NODE_NOTINIT | The calling node is not initialized. 3318 * \c MTAPI_ERR_PARAMETER | Invalid attributes parameter. 3319 * 3320 * \see mtapi_task_start(), mtapi_task_enqueue(), mtapi_groupattr_init(), 3321 * mtapi_groupattr_set() 3322 * 3323 * \returns Handle to newly created group, invalid handle on error 3324 * \threadsafe 3325 * \memory This function allocates a new queue for tracking completion of the 3326 * tasks belonging to the group. 3327 * \ingroup TASK_GROUPS 3328 */ 3329 mtapi_group_hndl_t mtapi_group_create( 3330 MTAPI_IN mtapi_group_id_t group_id, /**< [in] Group id */ 3331 MTAPI_IN mtapi_group_attributes_t* attributes, 3332 /**< [in] Pointer to attributes */ 3333 MTAPI_OUT mtapi_status_t* status /**< [out] Pointer to error code, 3334 may be \c MTAPI_NULL */ 3335 ); 3336 3337 /** 3338 * Changes the value of the attribute that corresponds to the given 3339 * \c attribute_num for the specified task group. 3340 * 3341 * \c attribute must point to the attribute value, and \c attribute_size must 3342 * be set to the exact size of the attribute value. See mtapi_groupattr_set() 3343 * for a list of predefined attribute numbers and the sizes of their values. 3344 * 3345 * On success, \c *status is set to \c MTAPI_SUCCESS. On error, \c *status is 3346 * set to the appropriate error defined below. 3347 * Error code | Description 3348 * -------------------------- | ----------------------------------------------- 3349 * \c MTAPI_ERR_PARAMETER | Invalid attribute parameter. 3350 * \c MTAPI_ERR_GROUP_INVALID | Argument is not a valid group handle. 3351 * \c MTAPI_ERR_ATTR_NUM | Unknown attribute number. 3352 * \c MTAPI_ERR_ATTR_SIZE | Incorrect attribute size. 3353 * \c MTAPI_ERR_NODE_NOTINIT | The calling node is not initialized. 3354 * 3355 * \see mtapi_groupattr_set() 3356 * 3357 * \notthreadsafe 3358 * \ingroup TASK_GROUPS 3359 */ 3360 void mtapi_group_set_attribute( 3361 MTAPI_IN mtapi_group_hndl_t group, /**< [in] Group handle */ 3362 MTAPI_IN mtapi_uint_t attribute_num, /**< [in] Attribute id */ 3363 MTAPI_OUT void* attribute, /**< [out] Pointer to attribute value */ 3364 MTAPI_IN mtapi_size_t attribute_size, 3365 /**< [in] Size of attribute value. may 3366 be 0, attribute is interpreted as 3367 value in that case */ 3368 MTAPI_OUT mtapi_status_t* status /**< [out] Pointer to error code, 3369 may be \c MTAPI_NULL */ 3370 ); 3371 3372 /** 3373 * Returns the attribute value that corresponds to the given \c attribute_num 3374 * for this task group. 3375 * 3376 * \c attribute must point to the location where the attribute value is to be 3377 * returned, and \c attribute_size must be set to the exact size of the 3378 * attribute value. See mtapi_groupattr_set() for a list of predefined 3379 * attribute numbers and the sizes of their values. 3380 * 3381 * On success, \c *status is set to \c MTAPI_SUCCESS and the attribute value is 3382 * returned in \c *attribute. On error, \c *status is set to the appropriate 3383 * error defined below and \c *attribute is undefined. If this function is 3384 * called on a group that no longer exists, an \c MTAPI_ERR_GROUP_INVALID 3385 * error code will be returned. 3386 * Error code | Description 3387 * -------------------------- | ----------------------------------------------- 3388 * \c MTAPI_ERR_PARAMETER | Invalid attribute parameter. 3389 * \c MTAPI_ERR_GROUP_INVALID | Argument is not a valid group handle. 3390 * \c MTAPI_ERR_ATTR_NUM | Unknown attribute number. 3391 * \c MTAPI_ERR_ATTR_SIZE | Incorrect attribute size. 3392 * \c MTAPI_ERR_NODE_NOTINIT | The calling node is not initialized. 3393 * 3394 * \see mtapi_groupattr_set() 3395 * 3396 * \waitfree 3397 * \ingroup TASK_GROUPS 3398 */ 3399 void mtapi_group_get_attribute( 3400 MTAPI_IN mtapi_group_hndl_t group, /**< [in] Group handle */ 3401 MTAPI_IN mtapi_uint_t attribute_num, /**< [in] Attribute id */ 3402 MTAPI_OUT void* attribute, /**< [out] Pointer to attribute value */ 3403 MTAPI_IN mtapi_size_t attribute_size,/**< [in] Size of attribute value */ 3404 MTAPI_OUT mtapi_status_t* status /**< [out] Pointer to error code, 3405 may be \c MTAPI_NULL */ 3406 ); 3407 3408 /** 3409 * This function waits for the completion of a task group. 3410 * 3411 * Tasks may be associated with groups when the tasks are started. Each task 3412 * is associated with one or more actions. This function returns when all the 3413 * associated action functions have completed or canceled. The group handle 3414 * becomes invalid if this function returns \c MTAPI_SUCCESS. 3415 * 3416 * \c timeout determines how long the function should wait for tasks already 3417 * started in the group to finish. The underlying type of \c mtapi_timeout_t is 3418 * implementation-defined. If \c timeout is a constant 0 or the symbolic 3419 * constant \c MTAPI_NOWAIT, this function does not block and returns 3420 * immediately. If \c timeout is set to \c MTAPI_INFINITE the function may 3421 * block infinitely. Other values for \c timeout and the units of measure are 3422 * implementation defined. 3423 * 3424 * To obtain results from a task, the application should call 3425 * mtapi_group_wait_any() instead. 3426 * 3427 * During execution, an action function may optionally call 3428 * mtapi_context_status_set() to set a task status that will be returned in 3429 * this function in \c *status. If multiple action functions set different task 3430 * status values, it is implementation-defined which of those is returned in 3431 * mtapi_group_wait_all(). The following task status values may be set by an 3432 * action function: \c MTAPI_ERR_TASK_CANCELLED, \c MTAPI_ERR_ACTION_CANCELLED, 3433 * \c MTAPI_ERR_ACTION_FAILED, and \c MTAPI_ERR_ACTION_DELETED. 3434 * 3435 * On success, \c *status is set to \c MTAPI_SUCCESS. On error, \c *status is 3436 * set to the appropriate error defined below. 3437 * <table> 3438 * <tr> 3439 * <th>Error code</th> 3440 * <th>Description</th> 3441 * </tr> 3442 * <tr> 3443 * <td>\c MTAPI_TIMEOUT</td> 3444 * <td>Timeout was reached.</td> 3445 * </tr> 3446 * <tr> 3447 * <td>\c MTAPI_ERR_GROUP_INVALID</td> 3448 * <td>Argument is not a valid task handle.</td> 3449 * </tr> 3450 * <tr> 3451 * <td>\c MTAPI_ERR_WAIT_PENDING</td> 3452 * <td>mtapi_group_wait_all() had already been called for the same group 3453 * and the first wait call is still pending.</td> 3454 * </tr> 3455 * <tr> 3456 * <td>\c MTAPI_ERR_PARAMETER</td> 3457 * <td>Invalid timeout parameter.</td> 3458 * </tr> 3459 * <tr> 3460 * <td>\c MTAPI_ERR_ARG_SIZE</td> 3461 * <td>The size of the arguments expected by action differs from arguments 3462 * size of the caller.</td> 3463 * </tr> 3464 * <tr> 3465 * <td>\c MTAPI_ERR_RESULT_SIZE</td> 3466 * <td>The size of the result buffer expected by action differs from 3467 * result buffer size of the caller.</td> 3468 * </tr> 3469 * <tr> 3470 * <td>\c MTAPI_ERR_NODE_NOTINIT</td> 3471 * <td>The calling node is not initialized.</td> 3472 * </tr> 3473 * <tr> 3474 * <td>\c MTAPI_GROUP_COMPLETED</td> 3475 * <td>Group completed, i.e., there are no more task to wait for in 3476 * the group.</td> 3477 * </tr> 3478 * <tr> 3479 * <td>\c MTAPI_ERR_TASK_CANCELLED</td> 3480 * <td>At least one task has been canceled because of mtapi_task_cancel() 3481 * was called before the task was executed or the error code was set 3482 * to \c MTAPI_ERR_TASK_CANCELLED by mtapi_context_status_set() in the 3483 * action function.</td> 3484 * </tr> 3485 * <tr> 3486 * <td>\c MTAPI_ERR_ACTION_CANCELLED</td> 3487 * <td>The action execution of at least one task was canceled by the 3488 * action function (mtapi_context_status_set()).</td> 3489 * </tr> 3490 * <tr> 3491 * <td>\c MTAPI_ERR_ACTION_FAILED</td> 3492 * <td>Error set by at least one action function 3493 * (mtapi_context_status_set()).</td> 3494 * </tr> 3495 * <tr> 3496 * <td>\c MTAPI_ERR_ACTION_DELETED</td> 3497 * <td>All actions associated with the task have been deleted before the 3498 * execution of the task was started or the error code has been set in 3499 * the action function to \c MTAPI_ERR_ACTION_DELETED by 3500 * mtapi_context_status_set().</td> 3501 * </tr> 3502 * </table> 3503 * 3504 * \see mtapi_group_wait_any(), mtapi_context_status_set(), mtapi_task_cancel() 3505 * 3506 * \threadsafe 3507 * \ingroup TASK_GROUPS 3508 */ 3509 void mtapi_group_wait_all( 3510 MTAPI_IN mtapi_group_hndl_t group, /**< [in] Group handle */ 3511 MTAPI_IN mtapi_timeout_t timeout, /**< [in] Timeout duration in 3512 milliseconds */ 3513 MTAPI_OUT mtapi_status_t* status /**< [out] Pointer to error code, 3514 may be \c MTAPI_NULL */ 3515 ); 3516 3517 /** 3518 * This function waits for the completion of any task in a task group. 3519 * 3520 * Tasks may be associated with groups when the tasks are started. Each task 3521 * is associated with one or more actions. This function returns when any of 3522 * the associated action functions have completed or have been canceled. 3523 * 3524 * The group handle does not become invalid if this function returns 3525 * \c MTAPI_SUCCESS. The group handle becomes invalid if this function returns 3526 * \c MTAPI_GROUP_COMPLETED. 3527 * 3528 * \c group must be a valid group handle obtained by a previous call to 3529 * mtapi_group_create(). 3530 * 3531 * Action functions may pass results that will be available in \c *result after 3532 * mtapi_group_wait_any() returns. If the results are not needed, \c result may 3533 * be set to \c MTAPI_NULL. Otherwise, \c result must point to an area in 3534 * memory of sufficient size to hold the array of results from the completed 3535 * task(s). The size of the result buffer is given in the argument 3536 * \c result_buffer_size that the runtime passes to an action function upon 3537 * invocation. 3538 * 3539 * \c timeout determines how long the function should wait for a task in the 3540 * group to finish. The underlying type of \c mtapi_timeout_t is 3541 * implementation-defined. If \c timeout is a constant 0 or the symbolic 3542 * constant \c MTAPI_NOWAIT, this function does not block and returns 3543 * immediately. If \c timeout is set to \c MTAPI_INFINITE the function may 3544 * block infinitely. Other values for \c timeout and the units of measure are 3545 * implementation defined. 3546 * 3547 * During execution, an action function may optionally call 3548 * mtapi_context_status_set() to set a task status that will be returned in 3549 * this function in \c *status. The following task status values may be set by 3550 * an action function: \c MTAPI_ERR_TASK_CANCELLED, 3551 * \c MTAPI_ERR_ACTION_CANCELLED, \c MTAPI_ERR_ACTION_FAILED, and 3552 * \c MTAPI_ERR_ACTION_DELETED. 3553 * 3554 * On success, \c *status is either set to \c MTAPI_SUCCESS if one of the 3555 * tasks in the group completed or to \c MTAPI_GROUP_COMPLETED if all tasks of 3556 * the group have completed and successfully waited for. On error, \c *status 3557 * is set to the appropriate error defined below. 3558 * <table> 3559 * <tr> 3560 * <th>Error code</th> 3561 * <th>Description</th> 3562 * </tr> 3563 * <tr> 3564 * <td>\c MTAPI_TIMEOUT</td> 3565 * <td>Timeout was reached.</td> 3566 * </tr> 3567 * <tr> 3568 * <td>\c MTAPI_ERR_GROUP_INVALID</td> 3569 * <td>Argument is not a valid task handle.</td> 3570 * </tr> 3571 * <tr> 3572 * <td>\c MTAPI_ERR_PARAMETER</td> 3573 * <td>Invalid timeout parameter.</td> 3574 * </tr> 3575 * <tr> 3576 * <td>\c MTAPI_ERR_ARG_SIZE</td> 3577 * <td>The size of the arguments expected by action differs from arguments 3578 * size of the caller.</td> 3579 * </tr> 3580 * <tr> 3581 * <td>\c MTAPI_ERR_RESULT_SIZE</td> 3582 * <td>The size of the result buffer expected by action differs from 3583 * result buffer size of the caller.</td> 3584 * </tr> 3585 * <tr> 3586 * <td>\c MTAPI_ERR_NODE_NOTINIT</td> 3587 * <td>The calling node is not initialized.</td> 3588 * </tr> 3589 * <tr> 3590 * <td>\c MTAPI_GROUP_COMPLETED</td> 3591 * <td>Group completed, i.e., there are no more tasks to wait for in 3592 * the group.</td> 3593 * </tr> 3594 * <tr> 3595 * <td>\c MTAPI_ERR_TASK_CANCELLED</td> 3596 * <td>The task has been canceled because mtapi_task_cancel() was called 3597 * before the task was executed, or the error code was set to 3598 * \c MTAPI_ERR_TASK_CANCELLED by mtapi_context_status_set() in the 3599 * action code.</td> 3600 * </tr> 3601 * <tr> 3602 * <td>\c MTAPI_ERR_ACTION_CANCELLED</td> 3603 * <td>Action execution was canceled by the action function 3604 * (mtapi_context_status_set()).</td> 3605 * </tr> 3606 * <tr> 3607 * <td>\c MTAPI_ERR_ACTION_FAILED</td> 3608 * <td>Error set by action function (mtapi_context_status_set()).</td> 3609 * </tr> 3610 * <tr> 3611 * <td>\c MTAPI_ERR_ACTION_DELETED</td> 3612 * <td>All actions associated with the task have been deleted before the 3613 * execution of the task was started or the error code has been set in 3614 * the action code to \c MTAPI_ERR_ACTION_DELETED 3615 * by mtapi_context_status_set().</td> 3616 * </tr> 3617 * </table> 3618 * 3619 * \see mtapi_group_create(), mtapi_context_status_set(), mtapi_task_cancel() 3620 * 3621 * \threadsafe 3622 * \ingroup TASK_GROUPS 3623 */ 3624 void mtapi_group_wait_any( 3625 MTAPI_IN mtapi_group_hndl_t group, /**< [in] Group handle */ 3626 MTAPI_OUT void** result, /**< [out] Pointer to result buffer 3627 supplied at task start */ 3628 MTAPI_IN mtapi_timeout_t timeout, /**< [in] Timeout duration in 3629 milliseconds */ 3630 MTAPI_OUT mtapi_status_t* status /**< [out] Pointer to error code, 3631 may be \c MTAPI_NULL */ 3632 ); 3633 3634 /** 3635 * This function deletes a task group. 3636 * 3637 * Deleting a group does not have any influence on tasks belonging to the 3638 * group. Adding tasks to a group that is already deleted will result in an 3639 * \c MTAPI_ERR_GROUP_INVALID error. 3640 * 3641 * On success, \c *status is set to \c MTAPI_SUCCESS. On error, \c *status is 3642 * set to the appropriate error defined below. 3643 * Error code | Description 3644 * -------------------------- | ----------------------------------------------- 3645 * \c MTAPI_ERR_GROUP_INVALID | Argument is not a valid group handle. 3646 * \c MTAPI_ERR_NODE_NOTINIT | The calling node is not initialized. 3647 * 3648 * \threadsafe 3649 * \ingroup TASK_GROUPS 3650 */ 3651 void mtapi_group_delete( 3652 MTAPI_IN mtapi_group_hndl_t group, /**< [in] Group handle */ 3653 MTAPI_OUT mtapi_status_t* status /**< [out] Pointer to error code, 3654 may be \c MTAPI_NULL */ 3655 ); 3656 3657 3658 /** 3659 * \internal 3660 * 3661 * \defgroup INTERNAL Internal Implementation 3662 * 3663 * \ingroup C_MTAPI 3664 * 3665 * This section describes the internal implementation of the MTAPI interface. 3666 */ 3667 3668 3669 #ifdef __cplusplus 3670 } 3671 #endif 3672 3673 #endif // EMBB_MTAPI_C_MTAPI_H_ 3674