/*
 * Copyright (c) 2004-2007 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 thread pool.
 */

#ifndef _CL_THREAD_POOL_H_
#define _CL_THREAD_POOL_H_

#include <pthread.h>
#include <complib/cl_types.h>
#include <complib/cl_thread.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/Thread Pool
* NAME
*	Thread Pool
*
* DESCRIPTION
*	The Thread Pool manages a user specified number of threads.
*
*	Each thread in the thread pool waits for a user initiated signal before
*	invoking a user specified callback function. All threads in the thread
*	pool invoke the same callback function.
*
*	The thread pool functions operate on a cl_thread_pool_t structure which
*	should be treated as opaque, and should be manipulated only through the
*	provided functions.
*
* SEE ALSO
*	Structures:
*		cl_thread_pool_t
*
*	Initialization:
*		cl_thread_pool_init, cl_thread_pool_destroy
*
*	Manipulation
*		cl_thread_pool_signal
*********/
/****s* Component Library: Thread Pool/cl_thread_pool_t
* NAME
*	cl_thread_pool_t
*
* DESCRIPTION
*	Thread pool structure.
*
*	The cl_thread_pool_t structure should be treated as opaque, and should be
*	manipulated only through the provided functions.
*
* SYNOPSIS
*/
typedef struct _cl_thread_pool {
	void (*pfn_callback) (void *);
	void *context;
	unsigned running_count;
	unsigned events;
	pthread_cond_t cond;
	pthread_mutex_t mutex;
	pthread_t *tid;
} cl_thread_pool_t;
/*
* FIELDS
*	pfn_callback
*		Callback function for the thread to invoke.
*
*	context
*		Context to pass to the thread callback function.
*
*	running_count
*		Number of threads running.
*
*	events
*		events counter
*
*	mutex
*		mutex for cond variable protection
*
*	cond
*		conditional variable to signal an event to thread
*
*	tid
*		array of allocated thread ids.
*
* SEE ALSO
*	Thread Pool
*********/

/****f* Component Library: Thread Pool/cl_thread_pool_init
* NAME
*	cl_thread_pool_init
*
* DESCRIPTION
*	The cl_thread_pool_init function creates the threads to be
*	managed by a thread pool.
*
* SYNOPSIS
*/
cl_status_t
cl_thread_pool_init(IN cl_thread_pool_t * const p_thread_pool,
		    IN unsigned count,
		    IN void (*pfn_callback) (void *),
		    IN void *context, IN const char *const name);
/*
* PARAMETERS
*	p_thread_pool
*		[in] Pointer to a thread pool structure to initialize.
*
*	thread_count
*		[in] Number of threads to be managed by the thread pool.
*
*	pfn_callback
*		[in] Address of a function to be invoked by a thread.
*		See the cl_pfn_thread_callback_t function type definition for
*		details about the callback function.
*
*	context
*		[in] Value to pass to the callback function.
*
*	name
*		[in] Name to associate with the threads.  The name may be up to 16
*		characters, including a terminating null character.  All threads
*		created in the pool have the same name.
*
* RETURN VALUES
*	CL_SUCCESS if the thread pool creation succeeded.
*
*	CL_INSUFFICIENT_MEMORY if there was not enough memory to inititalize
*	the thread pool.
*
*	CL_ERROR if the threads could not be created.
*
* NOTES
*	cl_thread_pool_init creates and starts the specified number of threads.
*	If thread_count is zero, the thread pool creates as many threads as there
*	are processors in the system.
*
* SEE ALSO
*	Thread Pool, cl_thread_pool_destroy,
*	cl_thread_pool_signal, cl_pfn_thread_callback_t
*********/

/****f* Component Library: Thread Pool/cl_thread_pool_destroy
* NAME
*	cl_thread_pool_destroy
*
* DESCRIPTION
*	The cl_thread_pool_destroy function performs any necessary cleanup
*	for a thread pool.
*
* SYNOPSIS
*/
void cl_thread_pool_destroy(IN cl_thread_pool_t * const p_thread_pool);
/*
* PARAMETERS
*	p_thread_pool
*		[in] Pointer to a thread pool structure to destroy.
*
* RETURN VALUE
*	This function does not return a value.
*
* NOTES
*	This function blocks until all threads exit, and must therefore not
*	be called from any of the thread pool's threads. Because of its blocking
*	nature, callers of cl_thread_pool_destroy must ensure that entering a wait
*	state is valid from the calling thread context.
*
*	This function should only be called after a call to
*	cl_thread_pool_init.
*
* SEE ALSO
*	Thread Pool, cl_thread_pool_init
*********/

/****f* Component Library: Thread Pool/cl_thread_pool_signal
* NAME
*	cl_thread_pool_signal
*
* DESCRIPTION
*	The cl_thread_pool_signal function signals a single thread of
*	the thread pool to invoke the thread pool's callback function.
*
* SYNOPSIS
*/
cl_status_t cl_thread_pool_signal(IN cl_thread_pool_t * const p_thread_pool);
/*
* PARAMETERS
*	p_thread_pool
*		[in] Pointer to a thread pool structure to signal.
*
* RETURN VALUES
*	CL_SUCCESS if the thread pool was successfully signalled.
*
*	CL_ERROR otherwise.
*
* NOTES
*	Each call to this function wakes up at most one waiting thread in
*	the thread pool.
*
*	If all threads are running, cl_thread_pool_signal has no effect.
*
* SEE ALSO
*	Thread Pool
*********/

END_C_DECLS
#endif				/* _CL_THREAD_POOL_H_ */