Main Page | Modules | Alphabetical List | Data Structures | File List | Data Fields | Globals

Cp_thread


Files

file  thread.h

Data Structures

struct  _cp_pooled_thread
struct  _cp_thread_pool
struct  cp_pooled_thread_scheduler
struct  _cp_pooled_thread_client_interface

Defines

#define SCHEDULER_THRESHOLD   1

Typedefs

typedef int(* cp_thread_stop_fn )(void *)
typedef CPROPS_DLL struct
_cp_pooled_thread 		cp_pooled_thread
typedef CPROPS_DLL struct
_cp_thread_pool 		cp_thread_pool
typedef CPROPS_DLL struct
cp_pooled_thread_scheduler 		cp_pooled_thread_scheduler
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

Functions

long cp_pooled_thread_get_id (cp_pooled_thread *pt)
cp_pooled_thread * cp_pooled_thread_create (cp_thread_pool *owner)
int cp_pooled_thread_stop (cp_pooled_thread *pt)
void cp_pooled_thread_destroy (cp_pooled_thread *t)
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)
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)
void * cp_pooled_thread_run (void *prm)
int cp_thread_pool_wait (cp_thread_pool *pool)
int cp_thread_pool_stop (cp_thread_pool *pool)
cp_thread_pool * cp_thread_pool_create (int min_size, int max_size)
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)
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)
cp_thread * cp_thread_pool_get_nb (cp_thread_pool *pool, cp_thread_action action, void *prm)
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)
void cp_thread_pool_destroy (cp_thread_pool *pool)
int cp_thread_pool_count_available (cp_thread_pool *pool)
cp_pooled_thread_client_interface * cp_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)
void cp_pooled_thread_client_interface_destroy (cp_pooled_thread_client_interface *client)
cp_pooled_thread_scheduler * cp_pooled_thread_scheduler_create (cp_thread_pool *pool)
void cp_pooled_thread_scheduler_destroy (cp_pooled_thread_scheduler *scheduler)
void cp_pooled_thread_scheduler_register_client (cp_pooled_thread_scheduler *scheduler, cp_pooled_thread_client_interface *client)
cp_pooled_thread_client_interface * choose_random_client (cp_pooled_thread_scheduler *scheduler)
void cp_pooled_thread_client_get_nb (cp_pooled_thread_client_interface *c)
void cp_pooled_thread_client_get (cp_pooled_thread_client_interface *c)
void cp_pooled_thread_client_get_stoppable_nb (cp_pooled_thread_client_interface *c)
void cp_pooled_thread_client_get_stoppable (cp_pooled_thread_client_interface *c)
void cp_pooled_thread_client_negociate (cp_pooled_thread_client_interface *c)
CPROPS_DLL cp_pooled_thread * cp_pooled_thread_create (struct _cp_thread_pool *owner)

Variables

__BEGIN_DECLS typedef void *(* cp_thread_action )(void *)

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.

Referenced by cp_pooled_thread_run(), cp_thread_pool_create(), and cp_thread_pool_stop().

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. 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

Referenced by cp_pooled_thread_client_interface_create(), cp_pooled_thread_client_interface_destroy(), cp_pooled_thread_client_negociate(), and cp_pooled_thread_scheduler_register_client().

typedef CPROPS_DLL struct cp_pooled_thread_scheduler cp_pooled_thread_scheduler
 

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.

Referenced by cp_thread_pool_create().

typedef int(* cp_thread_stop_fn)(void *)
 

a stop function for client threads

Definition at line 32 of file thread.h.

Referenced by cp_pooled_thread_client_interface_create().

Function Documentation

CPROPS_DLL 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

Definition at line 550 of file thread.c.

References _cp_pooled_thread_client_interface::count, and cp_thread_pool_get().

CPROPS_DLL 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

Definition at line 544 of file thread.c.

References _cp_pooled_thread_client_interface::count, and cp_thread_pool_get_nb().

CPROPS_DLL 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

Definition at line 562 of file thread.c.

References _cp_pooled_thread_client_interface::count, and cp_thread_pool_get_stoppable().

CPROPS_DLL 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

Definition at line 556 of file thread.c.

References _cp_pooled_thread_client_interface::count, and cp_thread_pool_get_stoppable_nb().

CPROPS_DLL cp_pooled_thread_client_interface * cp_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

Definition at line 457 of file thread.c.

References cp_fatal(), cp_pooled_thread_client_interface, cp_pooled_thread_scheduler_register_client(), cp_thread_action, cp_thread_stop_fn, and _cp_pooled_thread_client_interface::owner.

CPROPS_DLL void cp_pooled_thread_client_interface_destroy (  cp_pooled_thread_client_interface *  client  ) 
 

cp_pooled_thread_client_interface destructor

Definition at line 491 of file thread.c.

References cp_pooled_thread_client_interface.

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.

Definition at line 618 of file thread.c.

References _cp_pooled_thread_client_interface::count, cp_pooled_thread_client_interface, and cp_thread_pool_get_nb().

CPROPS_DLL cp_pooled_thread* cp_pooled_thread_create (  struct _cp_thread_pool *  owner  ) 
 

thread constructor function

Referenced by cp_thread_pool_create().

CPROPS_DLL void cp_pooled_thread_destroy (  cp_pooled_thread *  t  ) 
 

thread destructor

Definition at line 113 of file thread.c.

Referenced by cp_pooled_thread_run(), and cp_thread_pool_create().

CPROPS_DLL long cp_pooled_thread_get_id (  cp_pooled_thread *  thread  ) 
 

return a thread id for this thread

Definition at line 22 of file thread.c.

CPROPS_DLL void * cp_pooled_thread_run (  void *  prm  ) 
 

framework thread function

Definition at line 169 of file thread.c.

References cp_pooled_thread, cp_pooled_thread_destroy(), and _cp_pooled_thread::wait.

CPROPS_DLL 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

Definition at line 158 of file thread.c.

References cp_pooled_thread_run_task().

CPROPS_DLL 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'

Definition at line 131 of file thread.c.

References cp_error().

Referenced by cp_pooled_thread_run_stoppable_task().

CPROPS_DLL cp_pooled_thread_scheduler * cp_pooled_thread_scheduler_create (  cp_thread_pool *  pool  ) 
 

cp_pooled_thread_scheduler constructor

Definition at line 496 of file thread.c.

References cp_pooled_thread_scheduler::client_list, cp_fatal(), and cp_pooled_thread_scheduler::pool.

CPROPS_DLL void cp_pooled_thread_scheduler_destroy (  cp_pooled_thread_scheduler *  scheduler  ) 
 

cp_pooled_thread_scheduler destructor

Definition at line 515 of file thread.c.

References cp_pooled_thread_scheduler::client_list.

CPROPS_DLL 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

Definition at line 522 of file thread.c.

References cp_pooled_thread_client_interface.

Referenced by cp_pooled_thread_client_interface_create().

CPROPS_DLL int cp_pooled_thread_stop (  cp_pooled_thread *  t  ) 
 

signal a thread to stop

Definition at line 90 of file thread.c.

Referenced by cp_thread_pool_stop().

CPROPS_DLL int cp_thread_pool_count_available (  cp_thread_pool *  pool  ) 
 

returns the number of available threads in the pool.

Definition at line 442 of file thread.c.

References cp_list_item_count().

CPROPS_DLL cp_thread_pool * cp_thread_pool_create (  int  min_size,
int  max_size
) 
 

cp_thread_pool constructor

Definition at line 262 of file thread.c.

References cp_destructor_fn, cp_error(), cp_fatal(), cp_hash_compare_long(), cp_hash_long(), cp_hashlist_create, cp_hashlist_destroy_custom(), cp_list_append(), cp_list_create(), cp_list_destroy_custom(), cp_pooled_thread, cp_pooled_thread_create(), cp_pooled_thread_destroy(), cp_thread_pool, _cp_thread_pool::free_pool, _cp_thread_pool::in_use, _cp_thread_pool::max_size, _cp_thread_pool::min_size, _cp_thread_pool::pool_cond, _cp_thread_pool::pool_lock, and _cp_thread_pool::running.

Referenced by cp_httpclient_ctl_create(), and cp_socket_listen().

CPROPS_DLL void cp_thread_pool_destroy (  cp_thread_pool *  pool  ) 
 

cp_thread_pool destructor

Definition at line 420 of file thread.c.

References cp_hashlist_destroy(), cp_list_destroy(), and cp_thread_pool_stop().

Referenced by cp_httpclient_ctl_destroy(), and cp_socket_delete().

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.

Definition at line 388 of file thread.c.

Referenced by cp_pooled_thread_client_get().

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.

Definition at line 404 of file thread.c.

Referenced by cp_pooled_thread_client_get_nb(), and cp_pooled_thread_client_negociate().

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.

Definition at line 395 of file thread.c.

Referenced by cp_pooled_thread_client_get_stoppable().

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.

Definition at line 411 of file thread.c.

Referenced by cp_pooled_thread_client_get_stoppable_nb().

CPROPS_DLL int cp_thread_pool_stop (  cp_thread_pool *  pool  ) 
 

signal all threads in this pool to stop

Definition at line 241 of file thread.c.

References COLLECTION_LOCK_READ, cp_hashlist_create_iterator(), cp_hashlist_iterator, cp_hashlist_iterator_destroy(), cp_hashlist_iterator_next_value(), cp_list_create_iterator(), cp_list_iterator, cp_list_iterator_next(), cp_pooled_thread, and cp_pooled_thread_stop().

Referenced by cp_httpclient_ctl_destroy(), cp_socket_delete(), and cp_thread_pool_destroy().

CPROPS_DLL int cp_thread_pool_wait (  cp_thread_pool *  pool  ) 
 

wait for threads to finish processing client requests

Definition at line 225 of file thread.c.

References cp_hashlist_item_count().

Variable Documentation

__BEGIN_DECLS typedef void*(* cp_thread_action)(void *)
 

a thread function

Definition at line 28 of file thread.h.

Referenced by cp_pooled_thread_client_interface_create().

Generated on Sat Dec 1 10:25:30 2007 for cprops by  doxygen 1.3.9.1