|
Packit |
13e616 |
/*
|
|
Packit |
13e616 |
* Copyright (c) 2004, 2005 Voltaire, Inc. All rights reserved.
|
|
Packit |
13e616 |
* Copyright (c) 2002-2005 Mellanox Technologies LTD. All rights reserved.
|
|
Packit |
13e616 |
* Copyright (c) 1996-2003 Intel Corporation. All rights reserved.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* This software is available to you under a choice of one of two
|
|
Packit |
13e616 |
* licenses. You may choose to be licensed under the terms of the GNU
|
|
Packit |
13e616 |
* General Public License (GPL) Version 2, available from the file
|
|
Packit |
13e616 |
* COPYING in the main directory of this source tree, or the
|
|
Packit |
13e616 |
* OpenIB.org BSD license below:
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* Redistribution and use in source and binary forms, with or
|
|
Packit |
13e616 |
* without modification, are permitted provided that the following
|
|
Packit |
13e616 |
* conditions are met:
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* - Redistributions of source code must retain the above
|
|
Packit |
13e616 |
* copyright notice, this list of conditions and the following
|
|
Packit |
13e616 |
* disclaimer.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* - Redistributions in binary form must reproduce the above
|
|
Packit |
13e616 |
* copyright notice, this list of conditions and the following
|
|
Packit |
13e616 |
* disclaimer in the documentation and/or other materials
|
|
Packit |
13e616 |
* provided with the distribution.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
|
Packit |
13e616 |
* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
|
Packit |
13e616 |
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
|
|
Packit |
13e616 |
* NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
|
|
Packit |
13e616 |
* BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
|
|
Packit |
13e616 |
* ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
|
|
Packit |
13e616 |
* CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
Packit |
13e616 |
* SOFTWARE.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
*/
|
|
Packit |
13e616 |
|
|
Packit |
13e616 |
/*
|
|
Packit |
13e616 |
* Abstract:
|
|
Packit |
13e616 |
* Declaration of thread abstraction and thread related operations.
|
|
Packit |
13e616 |
*/
|
|
Packit |
13e616 |
|
|
Packit |
13e616 |
#ifndef _CL_THREAD_H_
|
|
Packit |
13e616 |
#define _CL_THREAD_H_
|
|
Packit |
13e616 |
|
|
Packit |
13e616 |
#include <complib/cl_thread_osd.h>
|
|
Packit |
13e616 |
|
|
Packit |
13e616 |
#ifdef __cplusplus
|
|
Packit |
13e616 |
# define BEGIN_C_DECLS extern "C" {
|
|
Packit |
13e616 |
# define END_C_DECLS }
|
|
Packit |
13e616 |
#else /* !__cplusplus */
|
|
Packit |
13e616 |
# define BEGIN_C_DECLS
|
|
Packit |
13e616 |
# define END_C_DECLS
|
|
Packit |
13e616 |
#endif /* __cplusplus */
|
|
Packit |
13e616 |
|
|
Packit |
13e616 |
BEGIN_C_DECLS
|
|
Packit |
13e616 |
/****i* Component Library/Thread
|
|
Packit |
13e616 |
* NAME
|
|
Packit |
13e616 |
* Thread
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* DESCRIPTION
|
|
Packit |
13e616 |
* The Thread provides a separate thread of execution.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* The cl_thread_t structure should be treated as opaque and should be
|
|
Packit |
13e616 |
* manipulated only through the provided functions.
|
|
Packit |
13e616 |
*********/
|
|
Packit |
13e616 |
/****d* Component Library: Thread/cl_pfn_thread_callback_t
|
|
Packit |
13e616 |
* NAME
|
|
Packit |
13e616 |
* cl_pfn_thread_callback_t
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* DESCRIPTION
|
|
Packit |
13e616 |
* The cl_pfn_thread_callback_t function type defines the prototype
|
|
Packit |
13e616 |
* for functions invoked by thread objects
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* SYNOPSIS
|
|
Packit |
13e616 |
*/
|
|
Packit |
13e616 |
typedef void (*cl_pfn_thread_callback_t) (IN void *context);
|
|
Packit |
13e616 |
/*
|
|
Packit |
13e616 |
* PARAMETERS
|
|
Packit |
13e616 |
* context
|
|
Packit |
13e616 |
* [in] Value specified in a call to cl_thread_init.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* RETURN VALUE
|
|
Packit |
13e616 |
* This function does not return a value.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* NOTES
|
|
Packit |
13e616 |
* This function type is provided as function prototype reference for
|
|
Packit |
13e616 |
* the function provided by users as a parameter to cl_thread_init.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* SEE ALSO
|
|
Packit |
13e616 |
* Thread Pool
|
|
Packit |
13e616 |
*********/
|
|
Packit |
13e616 |
|
|
Packit |
13e616 |
/****i* Component Library: Thread/cl_thread_t
|
|
Packit |
13e616 |
* NAME
|
|
Packit |
13e616 |
* cl_thread_t
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* DESCRIPTION
|
|
Packit |
13e616 |
* Thread structure.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* The cl_thread_t structure should be treated as opaque and should be
|
|
Packit |
13e616 |
* manipulated only through the provided functions.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* SYNOPSIS
|
|
Packit |
13e616 |
*/
|
|
Packit |
13e616 |
typedef struct _cl_thread {
|
|
Packit |
13e616 |
cl_thread_osd_t osd;
|
|
Packit |
13e616 |
cl_pfn_thread_callback_t pfn_callback;
|
|
Packit |
13e616 |
const void *context;
|
|
Packit |
13e616 |
char name[16];
|
|
Packit |
13e616 |
} cl_thread_t;
|
|
Packit |
13e616 |
/*
|
|
Packit |
13e616 |
* FIELDS
|
|
Packit |
13e616 |
* osd
|
|
Packit |
13e616 |
* Implementation specific structure for managing thread information.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* pfn_callback
|
|
Packit |
13e616 |
* Callback function for the thread to invoke.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* context
|
|
Packit |
13e616 |
* Context to pass to the thread callback function.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* name
|
|
Packit |
13e616 |
* Name to assign to the thread.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* SEE ALSO
|
|
Packit |
13e616 |
* Thread
|
|
Packit |
13e616 |
*********/
|
|
Packit |
13e616 |
|
|
Packit |
13e616 |
/****i* Component Library: Thread/cl_thread_construct
|
|
Packit |
13e616 |
* NAME
|
|
Packit |
13e616 |
* cl_thread_construct
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* DESCRIPTION
|
|
Packit |
13e616 |
* The cl_thread_construct function initializes the state of a thread.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* SYNOPSIS
|
|
Packit |
13e616 |
*/
|
|
Packit |
13e616 |
void cl_thread_construct(IN cl_thread_t * const p_thread);
|
|
Packit |
13e616 |
/*
|
|
Packit |
13e616 |
* PARAMETERS
|
|
Packit |
13e616 |
* p_thread
|
|
Packit |
13e616 |
* [in] Pointer to a cl_thread_t structure whose state to initialize.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* RETURN VALUE
|
|
Packit |
13e616 |
* This function does not return a value.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* NOTES
|
|
Packit |
13e616 |
* Allows calling cl_thread_destroy without first calling cl_thread_init.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* Calling cl_thread_construct is a prerequisite to calling any other
|
|
Packit |
13e616 |
* thread function except cl_thread_init.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* SEE ALSO
|
|
Packit |
13e616 |
* Thread, cl_thread_init, cl_thread_destroy
|
|
Packit |
13e616 |
*********/
|
|
Packit |
13e616 |
|
|
Packit |
13e616 |
/****i* Component Library: Thread/cl_thread_init
|
|
Packit |
13e616 |
* NAME
|
|
Packit |
13e616 |
* cl_thread_init
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* DESCRIPTION
|
|
Packit |
13e616 |
* The cl_thread_init function creates a new thread of execution.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* SYNOPSIS
|
|
Packit |
13e616 |
*/
|
|
Packit |
13e616 |
cl_status_t
|
|
Packit |
13e616 |
cl_thread_init(IN cl_thread_t * const p_thread,
|
|
Packit |
13e616 |
IN cl_pfn_thread_callback_t pfn_callback,
|
|
Packit |
13e616 |
IN const void *const context, IN const char *const name);
|
|
Packit |
13e616 |
/*
|
|
Packit |
13e616 |
* PARAMETERS
|
|
Packit |
13e616 |
* p_thread
|
|
Packit |
13e616 |
* [in] Pointer to a cl_thread_t structure to initialize.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* pfn_callback
|
|
Packit |
13e616 |
* [in] Address of a function to be invoked by a thread.
|
|
Packit |
13e616 |
* See the cl_pfn_thread_callback_t function type definition for
|
|
Packit |
13e616 |
* details about the callback function.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* context
|
|
Packit |
13e616 |
* [in] Value to pass to the callback function.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* name
|
|
Packit |
13e616 |
* [in] Name to associate with the thread. The name may be up to 16
|
|
Packit |
13e616 |
* characters, including a terminating null character.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* RETURN VALUES
|
|
Packit |
13e616 |
* CL_SUCCESS if thread creation succeeded.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* CL_ERROR if thread creation failed.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* NOTES
|
|
Packit |
13e616 |
* The thread created with cl_thread_init will invoke the callback
|
|
Packit |
13e616 |
* specified by the callback parameter with context as single parameter.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* The callback function is invoked once, and the thread exits when the
|
|
Packit |
13e616 |
* callback returns.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* It is invalid to call cl_thread_destroy from the callback function,
|
|
Packit |
13e616 |
* as doing so will result in a deadlock.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* SEE ALSO
|
|
Packit |
13e616 |
* Thread, cl_thread_construct, cl_thread_destroy, cl_thread_suspend,
|
|
Packit |
13e616 |
* cl_thread_stall, cl_pfn_thread_callback_t
|
|
Packit |
13e616 |
*********/
|
|
Packit |
13e616 |
|
|
Packit |
13e616 |
/****i* Component Library: Thread/cl_thread_destroy
|
|
Packit |
13e616 |
* NAME
|
|
Packit |
13e616 |
* cl_thread_destroy
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* DESCRIPTION
|
|
Packit |
13e616 |
* The cl_thread_destroy function performs any necessary cleanup to free
|
|
Packit |
13e616 |
* resources associated with the specified thread.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* SYNOPSIS
|
|
Packit |
13e616 |
*/
|
|
Packit |
13e616 |
void cl_thread_destroy(IN cl_thread_t * const p_thread);
|
|
Packit |
13e616 |
/*
|
|
Packit |
13e616 |
* PARAMETERS
|
|
Packit |
13e616 |
* p_thread
|
|
Packit |
13e616 |
* [in] Pointer to a cl_thread_t structure to destroy.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* RETURN VALUE
|
|
Packit |
13e616 |
* This function does not return a value.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* NOTES
|
|
Packit |
13e616 |
* This function blocks until the thread exits and must not be called by the
|
|
Packit |
13e616 |
* thread itself. Callers must therefore ensure that such a blocking call is
|
|
Packit |
13e616 |
* possible from the context of the call.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* This function must only be called after a call to cl_thread_construct or
|
|
Packit |
13e616 |
* cl_thread_init.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* SEE ALSO
|
|
Packit |
13e616 |
* Thread, cl_thread_construct, cl_thread_init
|
|
Packit |
13e616 |
*********/
|
|
Packit |
13e616 |
|
|
Packit |
13e616 |
/****f* Component Library: Thread/cl_thread_suspend
|
|
Packit |
13e616 |
* NAME
|
|
Packit |
13e616 |
* cl_thread_suspend
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* DESCRIPTION
|
|
Packit |
13e616 |
* The cl_thread_suspend function suspends the calling thread for a minimum
|
|
Packit |
13e616 |
* of the specified number of milliseconds.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* SYNOPSIS
|
|
Packit |
13e616 |
*/
|
|
Packit |
13e616 |
void cl_thread_suspend(IN const uint32_t pause_ms);
|
|
Packit |
13e616 |
/*
|
|
Packit |
13e616 |
* PARAMETERS
|
|
Packit |
13e616 |
* pause_ms
|
|
Packit |
13e616 |
* [in] Number of milliseconds to suspend the calling thread.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* RETURN VALUE
|
|
Packit |
13e616 |
* This function does not return a value.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* NOTES
|
|
Packit |
13e616 |
* This function should only be called if it is valid for the caller's thread
|
|
Packit |
13e616 |
* to enter a wait state. For stalling a thread that cannot enter a wait
|
|
Packit |
13e616 |
* state, callers should use cl_thread_stall.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* SEE ALSO
|
|
Packit |
13e616 |
* Thread, cl_thread_stall
|
|
Packit |
13e616 |
*********/
|
|
Packit |
13e616 |
|
|
Packit |
13e616 |
/****f* Component Library: Thread/cl_thread_stall
|
|
Packit |
13e616 |
* NAME
|
|
Packit |
13e616 |
* cl_thread_stall
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* DESCRIPTION
|
|
Packit |
13e616 |
* The cl_thread_stall function stalls the calling thread for a minimum of
|
|
Packit |
13e616 |
* the specified number of microseconds.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* SYNOPSIS
|
|
Packit |
13e616 |
*/
|
|
Packit |
13e616 |
void cl_thread_stall(IN const uint32_t pause_us);
|
|
Packit |
13e616 |
/*
|
|
Packit |
13e616 |
* PARAMETERS
|
|
Packit |
13e616 |
* pause_us
|
|
Packit |
13e616 |
* [in] Number of microseconds to stall the calling thread.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* RETURN VALUE
|
|
Packit |
13e616 |
* This function does not return a value.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* NOTES
|
|
Packit |
13e616 |
* The cl_thread_stall function performs a busy wait for the specified
|
|
Packit |
13e616 |
* number of microseconds. Care should be taken when using this function as
|
|
Packit |
13e616 |
* it does not relinquish its quantum of operation. For longer wait
|
|
Packit |
13e616 |
* operations, users should call cl_thread_suspend if possible.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* SEE ALSO
|
|
Packit |
13e616 |
* Thread, cl_thread_suspend
|
|
Packit |
13e616 |
*********/
|
|
Packit |
13e616 |
|
|
Packit |
13e616 |
/****f* Component Library: Thread/cl_proc_count
|
|
Packit |
13e616 |
* NAME
|
|
Packit |
13e616 |
* cl_proc_count
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* DESCRIPTION
|
|
Packit |
13e616 |
* The cl_proc_count function returns the number of processors in the system.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* SYNOPSIS
|
|
Packit |
13e616 |
*/
|
|
Packit |
13e616 |
int cl_proc_count(void);
|
|
Packit |
13e616 |
/*
|
|
Packit |
13e616 |
* RETURN VALUE
|
|
Packit |
13e616 |
* Returns the number of processors in the system.
|
|
Packit |
13e616 |
*********/
|
|
Packit |
13e616 |
|
|
Packit |
13e616 |
/****i* Component Library: Thread/cl_is_current_thread
|
|
Packit |
13e616 |
* NAME
|
|
Packit |
13e616 |
* cl_is_current_thread
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* DESCRIPTION
|
|
Packit |
13e616 |
* The cl_is_current_thread function compares the calling thread to the
|
|
Packit |
13e616 |
* specified thread and returns whether they are the same.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* SYNOPSIS
|
|
Packit |
13e616 |
*/
|
|
Packit |
13e616 |
boolean_t cl_is_current_thread(IN const cl_thread_t * const p_thread);
|
|
Packit |
13e616 |
/*
|
|
Packit |
13e616 |
* PARAMETERS
|
|
Packit |
13e616 |
* p_thread
|
|
Packit |
13e616 |
* [in] Pointer to a cl_thread_t structure to compare to the
|
|
Packit |
13e616 |
* caller's thead.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* RETURN VALUES
|
|
Packit |
13e616 |
* TRUE if the thread specified by the p_thread parameter is the
|
|
Packit |
13e616 |
* calling thread.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* FALSE otherwise.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* SEE ALSO
|
|
Packit |
13e616 |
* Thread, cl_threadinit_t
|
|
Packit |
13e616 |
*********/
|
|
Packit |
13e616 |
|
|
Packit |
13e616 |
/****f* Component Library: Thread/cl_is_blockable
|
|
Packit |
13e616 |
* NAME
|
|
Packit |
13e616 |
* cl_is_blockable
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* DESCRIPTION
|
|
Packit |
13e616 |
* The cl_is_blockable indicates if the current caller context is
|
|
Packit |
13e616 |
* blockable.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
* SYNOPSIS
|
|
Packit |
13e616 |
*/
|
|
Packit |
13e616 |
boolean_t cl_is_blockable(void);
|
|
Packit |
13e616 |
/*
|
|
Packit |
13e616 |
* RETURN VALUE
|
|
Packit |
13e616 |
* TRUE
|
|
Packit |
13e616 |
* Current caller context can be blocked, i.e it is safe to perform
|
|
Packit |
13e616 |
* a sleep, or call a down operation on a semaphore.
|
|
Packit |
13e616 |
*
|
|
Packit |
13e616 |
*********/
|
|
Packit |
13e616 |
|
|
Packit |
13e616 |
END_C_DECLS
|
|
Packit |
13e616 |
#endif /* _CL_THREAD_H_ */
|