1/* 2 * Copyright 2010-2013 Intel Corporation. 3 * 4 * This library is free software; you can redistribute it and/or modify it 5 * under the terms of the GNU Lesser General Public License as published 6 * by the Free Software Foundation, version 2.1. 7 * 8 * This library is distributed in the hope that it will be useful, 9 * but WITHOUT ANY WARRANTY; without even the implied warranty of 10 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 11 * Lesser General Public License for more details. 12 * 13 * You should have received a copy of the GNU Lesser General Public 14 * License along with this library; if not, write to the Free Software 15 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 16 * 02110-1301 USA. 17 * 18 * Disclaimer: The codes contained in these modules may be specific 19 * to the Intel Software Development Platform codenamed Knights Ferry, 20 * and the Intel product codenamed Knights Corner, and are not backward 21 * compatible with other Intel products. Additionally, Intel will NOT 22 * support the codes or instruction set in future products. 23 * 24 * Intel offers no warranty of any kind regarding the code. This code is 25 * licensed on an "AS IS" basis and Intel is not obligated to provide 26 * any support, assistance, installation, training, or other services 27 * of any kind. Intel is also not obligated to provide any updates, 28 * enhancements or extensions. Intel specifically disclaims any warranty 29 * of merchantability, non-infringement, fitness for any particular 30 * purpose, and any other warranty. 31 * 32 * Further, Intel disclaims all liability of any kind, including but 33 * not limited to liability for infringement of any proprietary rights, 34 * relating to the use of the code, even if Intel is notified of the 35 * possibility of such liability. Except as expressly stated in an Intel 36 * license agreement provided with this code and agreed upon with Intel, 37 * no license, express or implied, by estoppel or otherwise, to any 38 * intellectual property rights is granted herein. 39 */ 40 41#ifndef _COIEVENT_SOURCE_H 42#define _COIEVENT_SOURCE_H 43 44/** @ingroup COIEvent 45 * @addtogroup COIEventSource 46@{ 47* @file source/COIEvent_source.h 48*/ 49#ifndef DOXYGEN_SHOULD_SKIP_THIS 50 51#include "../common/COITypes_common.h" 52#include "../common/COIResult_common.h" 53 54#ifdef __cplusplus 55extern "C" { 56#endif 57#endif // DOXYGEN_SHOULD_SKIP_THIS 58/////////////////////////////////////////////////////////////////////////////// 59/// 60/// Special case event values which can be passed in to APIs to specify 61/// how the API should behave. In COIBuffer APIs passing in NULL for the 62/// completion event is the equivalent of passing COI_EVENT_SYNC. For 63/// COIPipelineRunFunction passing in NULL is the equivalent of 64/// COI_EVENT_ASYNC. 65/// Note that passing COI_EVENT_ASYNC can be used when the caller wishes the 66/// operation to be performed asynchronously but does not care when the 67/// operation completes. This can be useful for opertions that by definition 68/// must complete in order (DMAs, run functions on a single pipeline). If 69/// the caller does care when the operation completes then they should pass 70/// in a valid completion event which they can later wait on. 71/// 72#define COI_EVENT_ASYNC ((COIEVENT*)1) 73#define COI_EVENT_SYNC ((COIEVENT*)2) 74 75/////////////////////////////////////////////////////////////////////////////// 76/// 77/// Wait for an arbitrary number of COIEVENTs to be signaled as completed, 78/// eg when the run function or asynchronous map call associated with an event 79/// has finished execution. 80/// If the user sets in_WaitForAll = True and not all of the events are 81/// signaled when the timeout period is reached then COI_TIME_OUT_REACHED will 82/// be returned. 83/// If the user sets in_WaitForAll = False then if at least one event is 84/// signaled when the timeout is reached then COI_SUCCESS is returned. 85/// 86/// @param in_NumEvents 87/// [in] The number of events to wait for. 88/// 89/// @param in_pEvents 90/// [in] The array of COIEVENT handles to wait for. 91/// 92/// @param in_Timeout 93/// [in] The time in milliseconds to wait for the event. 0 polls 94/// and returns immediately, -1 blocks indefinitely. 95/// 96/// @param in_WaitForAll 97/// [in] Boolean value specifying behavior. If true, wait for all 98/// events to be signaled, or for timeout, whichever happens first. 99/// If false, return when any event is signaled, or at timeout. 100/// 101/// @param out_pNumSignaled 102/// [out] The number of events that were signaled. If in_NumEvents 103/// is 1 or in_WaitForAll = True, this parameter is optional. 104/// 105/// @param out_pSignaledIndices 106/// [out] Pointer to an array of indicies into the original event 107/// array. Those denoted have been signaled. The user must provide an 108/// array that is no smaller than the in_Events array. If in_NumEvents 109/// is 1 or in_WaitForAll = True, this parameter is optional. 110/// 111/// @return COI_SUCCESS once an event has been signaled completed. 112/// 113/// @return COI_TIME_OUT_REACHED if the events are still in use when the 114/// timeout is reached or timeout is zero (a poll). 115/// 116/// @return COI_OUT_OF_RANGE if a negative value other than -1 is passed in to 117/// the in_Timeout parameter. 118/// 119/// @return COI_OUT_OF_RANGE if in_NumEvents is 0. 120/// 121/// @return COI_INVALID_POINTER if in_pEvents is NULL. 122/// 123/// @return COI_ARGUMENT_MISMATCH if in_NumEvents > 1 and if in_WaitForAll 124/// is not true and out_pSignaled or out_pSignaledIndicies are NULL. 125/// 126/// @return COI_ARGUMENT_MISMATCH if out_pNumSignaled is not NULL 127/// and out_pSignaledIndices is NULL (or vice versa). 128/// 129/// @return COI_EVENT_CANCELED if while waiting on a user event, it gets 130/// unregistered this returns COI_EVENT_CANCELED 131/// 132/// @return COI_PROCESS_DIED if the remote process died. See COIProcessDestroy 133/// for more details. 134/// 135COIACCESSAPI 136COIRESULT 137COIEventWait( 138 uint16_t in_NumEvents, 139 const COIEVENT* in_pEvents, 140 int32_t in_TimeoutMilliseconds, 141 uint8_t in_WaitForAll, 142 uint32_t* out_pNumSignaled, 143 uint32_t* out_pSignaledIndices); 144 145 146 147/////////////////////////////////////////////////////////////////////////////// 148/// 149/// Register a User COIEVENT so that it can be fired. Registered event is 150/// a one shot User event; in other words once signaled it cannot be used 151/// again for signaling. You have to unregister and register again to enable 152/// signaling. An event will be reset if it is re-registered without 153/// unregistering, resulting in loss of all outstanding signals. 154/// 155/// @param out_pEvent 156/// [out] Pointer to COIEVENT handle being Registered 157/// 158/// @return COI_SUCCESS an event is successfully registered 159/// 160/// @return COI_INVALID_POINTER if out_pEvent is NULL 161/// 162COIACCESSAPI 163COIRESULT 164COIEventRegisterUserEvent( 165 COIEVENT* out_pEvent); 166 167 168/////////////////////////////////////////////////////////////////////////////// 169/// 170/// Unregister a User COIEVENT. Unregistering a unsignaled event is similar 171/// to firing an event. Except Calling COIEventWait on an event that is 172/// being unregistered returns COI_EVENT_CANCELED 173/// 174/// @param in_Event 175/// [in] Event Handle to be unregistered. 176/// 177/// @return COI_INVALID_HANDLE if in_Event is not a UserEvent 178/// 179/// @return COI_SUCCESS an event is successfully registered 180/// 181COIACCESSAPI 182COIRESULT 183COIEventUnregisterUserEvent( 184 COIEVENT in_Event); 185 186#ifdef __cplusplus 187} /* extern "C" */ 188#endif 189 190#endif /* _COIEVENT_SOURCE_H */ 191 192/*! @} */ 193