/*
* Copyright (c) 2004, 2005 Voltaire, Inc. All rights reserved.
* Copyright (c) 2002-2005 Mellanox Technologies LTD. All rights reserved.
* Copyright (c) 1996-2003 Intel Corporation. All rights reserved.
*
* This software is available to you under a choice of one of two
* licenses. You may choose to be licensed under the terms of the GNU
* General Public License (GPL) Version 2, available from the file
* COPYING in the main directory of this source tree, or the
* OpenIB.org BSD license below:
*
* Redistribution and use in source and binary forms, with or
* without modification, are permitted provided that the following
* conditions are met:
*
* - Redistributions of source code must retain the above
* copyright notice, this list of conditions and the following
* disclaimer.
*
* - Redistributions in binary form must reproduce the above
* copyright notice, this list of conditions and the following
* disclaimer in the documentation and/or other materials
* provided with the distribution.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
* NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
* BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
* ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
* CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
* SOFTWARE.
*
*/
/*
* Abstract:
* Declaration of event abstraction.
*/
#ifndef _CL_EVENT_H_
#define _CL_EVENT_H_
/* Indicates that waiting on an event should never timeout */
#define EVENT_NO_TIMEOUT 0xFFFFFFFF
#include <complib/cl_event_osd.h>
#ifdef __cplusplus
# define BEGIN_C_DECLS extern "C" {
# define END_C_DECLS }
#else /* !__cplusplus */
# define BEGIN_C_DECLS
# define END_C_DECLS
#endif /* __cplusplus */
BEGIN_C_DECLS
/****h* Component Library/Event
* NAME
* Event
*
* DESCRIPTION
* The Event provides the ability to suspend and wakeup a thread.
*
* The event functions operates on a cl_event_t structure which should be
* treated as opaque and should be manipulated only through the provided
* functions.
*
* SEE ALSO
* Structures:
* cl_event_t
*
* Initialization/Destruction:
* cl_event_construct, cl_event_init, cl_event_destroy
*
* Manipulation:
* cl_event_signal, cl_event_reset, cl_event_wait_on
*********/
/****f* Component Library: Event/cl_event_construct
* NAME
* cl_event_construct
*
* DESCRIPTION
* The cl_event_construct function constructs an event.
*
* SYNOPSIS
*/
void cl_event_construct(IN cl_event_t * const p_event);
/*
* PARAMETERS
* p_event
* [in] Pointer to an cl_event_t structure to construct.
*
* RETURN VALUE
* This function does not return a value.
*
* NOTES
* Allows calling cl_event_destroy without first calling cl_event_init.
*
* Calling cl_event_construct is a prerequisite to calling any other event
* function except cl_event_init.
*
* SEE ALSO
* Event, cl_event_init, cl_event_destroy
*********/
/****f* Component Library: Event/cl_event_init
* NAME
* cl_event_init
*
* DESCRIPTION
* The cl_event_init function initializes an event for use.
*
* SYNOPSIS
*/
cl_status_t
cl_event_init(IN cl_event_t * const p_event, IN const boolean_t manual_reset);
/*
* PARAMETERS
* p_event
* [in] Pointer to an cl_event_t structure to initialize.
*
* manual_reset
* [in] If FALSE, indicates that the event resets itself after releasing
* a single waiter. If TRUE, the event remains in the signalled state
* until explicitly reset by a call to cl_event_reset.
*
* RETURN VALUES
* CL_SUCCESS if event initialization succeeded.
*
* CL_ERROR otherwise.
*
* NOTES
* Allows calling event manipulation functions, such as cl_event_signal,
* cl_event_reset, and cl_event_wait_on.
*
* The event is initially in a reset state.
*
* SEE ALSO
* Event, cl_event_construct, cl_event_destroy, cl_event_signal,
* cl_event_reset, cl_event_wait_on
*********/
/****f* Component Library: Event/cl_event_destroy
* NAME
* cl_event_destroy
*
* DESCRIPTION
* The cl_event_destroy function performs any necessary cleanup of an event.
*
* SYNOPSIS
*/
void cl_event_destroy(IN cl_event_t * const p_event);
/*
* PARAMETERS
* p_event
* [in] Pointer to an cl_event_t structure to destroy.
*
* RETURN VALUE
* This function does not return a value.
*
* NOTES
* This function should only be called after a call to cl_event_construct
* or cl_event_init.
*
* SEE ALSO
* Event, cl_event_construct, cl_event_init
*********/
/****f* Component Library: Event/cl_event_signal
* NAME
* cl_event_signal
*
* DESCRIPTION
* The cl_event_signal function sets an event to the signalled state and
* releases at most one waiting thread.
*
* SYNOPSIS
*/
cl_status_t cl_event_signal(IN cl_event_t * const p_event);
/*
* PARAMETERS
* p_event
* [in] Pointer to an cl_event_t structure to set.
*
* RETURN VALUES
* CL_SUCCESS if the event was successfully signalled.
*
* CL_ERROR otherwise.
*
* NOTES
* For auto-reset events, the event is reset automatically once a wait
* operation is satisfied.
*
* Triggering the event multiple times does not guarantee that the same
* number of wait operations are satisfied. This is because events are
* either in a signalled on non-signalled state, and triggering an event
* that is already in the signalled state has no effect.
*
* SEE ALSO
* Event, cl_event_reset, cl_event_wait_on
*********/
/****f* Component Library: Event/cl_event_reset
* NAME
* cl_event_reset
*
* DESCRIPTION
* The cl_event_reset function sets an event to the non-signalled state.
*
* SYNOPSIS
*/
cl_status_t cl_event_reset(IN cl_event_t * const p_event);
/*
* PARAMETERS
* p_event
* [in] Pointer to an cl_event_t structure to reset.
*
* RETURN VALUES
* CL_SUCCESS if the event was successfully reset.
*
* CL_ERROR otherwise.
*
* SEE ALSO
* Event, cl_event_signal, cl_event_wait_on
*********/
/****f* Component Library: Event/cl_event_wait_on
* NAME
* cl_event_wait_on
*
* DESCRIPTION
* The cl_event_wait_on function waits for the specified event to be
* triggered for a minimum amount of time.
*
* SYNOPSIS
*/
cl_status_t
cl_event_wait_on(IN cl_event_t * const p_event,
IN const uint32_t wait_us, IN const boolean_t interruptible);
/*
* PARAMETERS
* p_event
* [in] Pointer to an cl_event_t structure on which to wait.
*
* wait_us
* [in] Number of microseconds to wait.
*
* interruptible
* [in] Indicates whether the wait operation can be interrupted
* by external signals.
*
* RETURN VALUES
* CL_SUCCESS if the wait operation succeeded in response to the event
* being set.
*
* CL_TIMEOUT if the specified time period elapses.
*
* CL_NOT_DONE if the wait was interrupted by an external signal.
*
* CL_ERROR if the wait operation failed.
*
* NOTES
* If wait_us is set to EVENT_NO_TIMEOUT, the function will wait until the
* event is triggered and never timeout.
*
* If the timeout value is zero, this function simply tests the state of
* the event.
*
* If the event is already on the signalled state at the time of the call
* to cl_event_wait_on, the call completes immediately with CL_SUCCESS.
*
* SEE ALSO
* Event, cl_event_signal, cl_event_reset
*********/
END_C_DECLS
#endif /* _CL_EVENT_H_ */