Data Structures | Files | Defines | Typedefs | Functions | Variables

Cp_thread

Data Structures

struct  _cp_pooled_thread
 cp_pooled_thread is a thread that lives in a thread_pool. More...
struct  _cp_thread_pool
 cp_thread_pool holds a list of free threads (in wait mode). More...
struct  cp_pooled_thread_scheduler
 Definitions for thread management framework follow. More...
struct  _cp_pooled_thread_client_interface
 cp_pooled_thread_client_interface acts as the link to the cp_pooled_thread_scheduler for clients that require a variable number of threads. More...

Files

file  thread.h
 

definitions for the thread management framework.


Defines

#define SCHEDULER_THRESHOLD   1

Typedefs

typedef int(* cp_thread_stop_fn )(void *)
 a stop function for client threads
typedef CPROPS_DLL struct
_cp_pooled_thread 
cp_pooled_thread
 cp_pooled_thread is a thread that lives in a thread_pool.
typedef CPROPS_DLL struct
_cp_thread_pool 
cp_thread_pool
 cp_thread_pool holds a list of free threads (in wait mode).
typedef CPROPS_DLL struct
cp_pooled_thread_scheduler 
cp_pooled_thread_scheduler
 Definitions for thread management framework follow.
typedef int cp_pooled_thread_report_load (struct _cp_pooled_thread_client_interface *s)
typedef void cp_pooled_thread_shrink (struct _cp_pooled_thread_client_interface *)
typedef CPROPS_DLL struct
_cp_pooled_thread_client_interface 
cp_pooled_thread_client_interface
 cp_pooled_thread_client_interface acts as the link to the cp_pooled_thread_scheduler for clients that require a variable number of threads.

Functions

static int cp_thread_pool_set_available (cp_thread_pool *owner, cp_pooled_thread *pt)
 internal function to return a cp_pooled_thread to the available pool
long cp_pooled_thread_get_id (cp_pooled_thread *thread)
 return a thread id for this thread
cp_pooled_threadcp_pooled_thread_create (cp_thread_pool *owner)
int cp_pooled_thread_stop (cp_pooled_thread *t)
 signal a thread to stop
void cp_pooled_thread_destroy (cp_pooled_thread *t)
 thread destructor
int cp_pooled_thread_release (cp_pooled_thread *t)
int cp_pooled_thread_run_task (cp_pooled_thread *pt, cp_thread_action action, void *prm)
 sets the action and prm for this thread, then invokes 'action'
int cp_pooled_thread_run_stoppable_task (cp_pooled_thread *pt, cp_thread_action action, void *action_prm, cp_thread_stop_fn stop_fn, void *stop_prm)
 perform action with stop function
void * cp_pooled_thread_run (void *prm)
 framework thread function
int cp_thread_pool_wait (cp_thread_pool *pool)
 wait for threads to finish processing client requests
int cp_thread_pool_stop (cp_thread_pool *pool)
 signal all threads in this pool to stop
cp_thread_poolcp_thread_pool_create (int min_size, int max_size)
 cp_thread_pool constructor
cp_thread * cp_thread_pool_get_impl (cp_thread_pool *pool, cp_thread_action action, void *action_prm, cp_thread_stop_fn stop_fn, void *stop_prm, int block)
cp_thread * cp_thread_pool_get (cp_thread_pool *pool, cp_thread_action action, void *prm)
 request a thread from the pool.
cp_thread * cp_thread_pool_get_stoppable (cp_thread_pool *pool, cp_thread_action action, void *action_prm, cp_thread_stop_fn stop_fn, void *stop_prm)
 request a thread from the pool.
cp_thread * cp_thread_pool_get_nb (cp_thread_pool *pool, cp_thread_action action, void *prm)
 request a thread from the pool - non-blocking version.
cp_thread * cp_thread_pool_get_stoppable_nb (cp_thread_pool *pool, cp_thread_action action, void *action_prm, cp_thread_stop_fn stop_fn, void *stop_prm)
 request a thread from the pool - non-blocking version.
void cp_thread_pool_destroy (cp_thread_pool *pool)
 cp_thread_pool destructor
int cp_thread_pool_count_available (cp_thread_pool *pool)
 returns the number of available threads in the pool.
cp_pooled_thread_client_interfacecp_pooled_thread_client_interface_create (cp_pooled_thread_scheduler *owner, void *client, int min_threads, int max_threads, cp_pooled_thread_report_load report_load, cp_pooled_thread_shrink shrink, cp_thread_action action, void *action_prm, cp_thread_stop_fn stop_fn, void *stop_prm)
 cp_pooled_thread_client_interface constructor
void cp_pooled_thread_client_interface_destroy (cp_pooled_thread_client_interface *client)
 cp_pooled_thread_client_interface destructor
cp_pooled_thread_schedulercp_pooled_thread_scheduler_create (cp_thread_pool *pool)
 cp_pooled_thread_scheduler constructor
void cp_pooled_thread_scheduler_destroy (cp_pooled_thread_scheduler *scheduler)
 cp_pooled_thread_scheduler destructor
void cp_pooled_thread_scheduler_register_client (cp_pooled_thread_scheduler *scheduler, cp_pooled_thread_client_interface *client)
 register client as a client of this scheduler
cp_pooled_thread_client_interfacechoose_random_client (cp_pooled_thread_scheduler *scheduler)
void cp_pooled_thread_client_get_nb (cp_pooled_thread_client_interface *c)
 convenience to abstract cp_thread_pool based implementation, see cp_pooled_thread_get and cp_pooled_thread_get_nb
void cp_pooled_thread_client_get (cp_pooled_thread_client_interface *c)
 convenience to abstract cp_thread_pool based implementation, see cp_pooled_thread_get and cp_pooled_thread_get_nb
void cp_pooled_thread_client_get_stoppable_nb (cp_pooled_thread_client_interface *c)
 convenience to abstract cp_thread_pool based implementation, see cp_pooled_thread_get and cp_pooled_thread_get_nb
void cp_pooled_thread_client_get_stoppable (cp_pooled_thread_client_interface *c)
 convenience to abstract cp_thread_pool based implementation, see cp_pooled_thread_get and cp_pooled_thread_get_nb
void cp_pooled_thread_client_negociate (cp_pooled_thread_client_interface *c)
 threads should call negociate when a change in the number of threads a client owns is required.
CPROPS_DLL cp_pooled_threadcp_pooled_thread_create (struct _cp_thread_pool *owner)
 thread constructor function

Variables

__BEGIN_DECLS typedef void *(* cp_thread_action )(void *)
 a thread function

Typedef Documentation

typedef CPROPS_DLL struct _cp_pooled_thread cp_pooled_thread

cp_pooled_thread is a thread that lives in a thread_pool.

The struct holds synchronization elements used to control the thread and actuation settings, i.e. a thread function and a parameter to be passed for the next starting thread. The pool initializes a bunch of threads and sets them in 'wait'.

When a client requests threads from the pool, the next available thread is signalled out of 'wait', and runs the thread function requested by the client (see cp_thread_pool_get_impl). When the client thread function is done, the cp_pooled_thread returns to the thread pool and becomes available to pool clients. The cp_pooled_thread only exits when the pool exits, unless explicitly stopped (eg pthread_exit) by client code.

cp_pooled_thread_client_interface acts as the link to the cp_pooled_thread_scheduler for clients that require a variable number of threads.

This interface holds 3 functions pointers that must be supplied by a client:
report_load - should return the number of open requests the client has to handle shrink - will be called by the framework to stop one client thread action - the thread function for this client

Definitions for thread management framework follow.

The framework is based on the cp_thread_pool and cp_pooled_thread types.
The pooled thread scheduler interface is meant for use by clients who require a variable number of threads. Each such component should create an instance of cp_pooled_thread_client_interface and use the api functions to get threads from the underlying cp_thread_pool. Here is some example code.

 cp_pooled_thread_scheduler *main_scheduler;

 ...

 component_a_start(component_a *a, ...)
 {
     a->scheduler_interface = 
         cp_pooled_thread_client_interface_create(main_scheduler, a, 2, 10, 
             component_a_report_load, component_a_stop_thread, 
             component_a_thread_run, a);

     ...

     for (i = 0; i < a->scheduler_interface->min; i++)
         cp_pooled_thread_client_get(a->scheduler_interface);
 }

 component_b_start(component_b *b, ...)
 {
     b->scheduler_interface = 
         cp_pooled_thread_client_interface_create(main_scheduler, b, 2, 10, 
             component_a_report_load, component_a_stop_thread, 
             component_a_thread_run, b);

     ...

     for (i = 0; i < b->scheduler_interface->min; i++)
         cp_pooled_thread_client_get(b->scheduler_interface);
 }

 


In this example, the threads for component_a and component_b will be managed jointly, since their cp_pooled_thread_client_interface *'s have the same cp_pooled_thread_scheduler *.

See cp_pooled_thread_client_negociate for details.

typedef CPROPS_DLL struct _cp_thread_pool cp_thread_pool

cp_thread_pool holds a list of free threads (in wait mode).

The list grows up to max_size, after which subsequent calls to cp_thread_pool_get will block, and calls to cp_thread_pool_get_nb will return NULL - until clients return their threads to the pool.


Function Documentation

CPROPS_DLL void cp_pooled_thread_client_negociate ( cp_pooled_thread_client_interface c  ) 

threads should call negociate when a change in the number of threads a client owns is required.

Two possible scheduling approaches are -

(1) centralized: Clients report their load factor to the thread manager. The thread manager grants requests for new threads to clients with higher loads first.

(2) distributed: clients negociate with other clients requesting a thread based on their load factors. The client with the lower load factor releases a thread to the client with the higher load factor.

The distributed approach saves some bookkeeping over head in the thread manager, reduces the number steps involved in acquiring a new thread or releasing an unused one, and makes a dedicated synchronization thread unnecessary.

In the current implementation, the scheduler will randomly choose one other client to negociate with. If the load factors are different enough, one thread will be switched to the busier client.

CPROPS_DLL long cp_pooled_thread_get_id ( cp_pooled_thread pt  ) 

return a thread id for this thread

retrieve an integer type thread id for this thread

CPROPS_DLL int cp_thread_pool_count_available ( cp_thread_pool pool  ) 

returns the number of available threads in the pool.

CPROPS_DLL cp_thread * cp_thread_pool_get ( cp_thread_pool pool,
cp_thread_action  action,
void *  prm 
)

request a thread from the pool.

If no threads are available, this function will block until a thread becomes available.

CPROPS_DLL cp_thread * cp_thread_pool_get_nb ( cp_thread_pool pool,
cp_thread_action  action,
void *  prm 
)

request a thread from the pool - non-blocking version.

Returns a pointer to the requested thread if one is available or NULL if the pool is empty.

CPROPS_DLL cp_thread * cp_thread_pool_get_stoppable ( cp_thread_pool pool,
cp_thread_action  action,
void *  action_prm,
cp_thread_stop_fn  stop_fn,
void *  stop_prm 
)

request a thread from the pool.

If no threads are available, this function will block until a thread becomes available.

CPROPS_DLL cp_thread * cp_thread_pool_get_stoppable_nb ( cp_thread_pool pool,
cp_thread_action  action,
void *  action_prm,
cp_thread_stop_fn  stop_fn,
void *  stop_prm 
)

request a thread from the pool - non-blocking version.

Returns a pointer to the requested thread if one is available or NULL if the pool is empty.