The "mt" Package

These routines are meant to provide management of a pool of threads which may execute concurrently.

Library: karma
Link With: -lkarma

Functions

mt_create_pool	Create a pool of threads which may have jobs launched onto it.
mt_get_shared_pool	Create or get the shared thread pool.
mt_destroy_pool	This routine will destroy a thread pool.
mt_destroy_all_pools	This routine will destroy all thread pools.
mt_num_threads	Get the number of threads in a thread pool.
mt_num_processors	Get the number of processors available on the system.
mt_launch_job	Launch a job onto a thread pool.
mt_setlock	Set a lock on a thread pool.
mt_new_thread_info	Register new thread information for the threads in a pool.
mt_get_thread_info	Get the thread information pointer for a pool of threads.
mt_wait_for_all_jobs	Wait for all previously launched jobs to complete.
mt_get_notify_pipe	Create/get the notification pipe.
mt_disable_notify_pipe	Disable the notification pipe.

Prototype Functions

mt_PROTO_func

Perform a job.

Functions

KThreadPool mt_create_pool (void *pool_info)

Create a pool of threads which may have jobs launched onto it.

Parameters:

pool_info : An arbitrary pointer passed to work functions.

Returns: A KThreadPool object on success, else NULL.
Multithreading Level: Safe under Solaris 2.
Note:

The environment variable MT_MAX_THREADS may be used to limit the number of threads used.

KThreadPool mt_get_shared_pool ()

This routine will get a pool of threads which may be shared between several services within a process. This shared pool may be used to reduce the number of thread pools created. Creating large numbers of thread pools may consume significant system resources on some platforms. The first time this routine is called the shared pool is created.

Parameters:

Returns: The shared KThreadPool object on success. On failure the process aborts.
Multithreading Level: Safe under Solaris 2.
Note:

The environment variable MT_MAX_THREADS may be used to limit the number of threads used.
This shared pool cannot be used with the mt_new_thread_info and mt_get_thread_info routines.

void mt_destroy_pool (KThreadPool pool, flag interrupt)

This routine will destroy a thread pool.

Parameters:

pool : The thread pool.
interrupt : If TRUE, any jobs not yet completed will be killed, else the function will wait for uncompleted jobs to finish prior to destroying the pool.

Returns: Nothing.
Multithreading Level: Safe.

void mt_destroy_all_pools (flag interrupt)

This routine will destroy all thread pools.

Parameters:

interrupt : If TRUE, any jobs not yet completed will be killed, else the function will wait for uncompleted jobs to finish prior to destroying the pools.

Returns: Nothing.
Multithreading Level: Safe.

unsigned int mt_num_threads (KThreadPool pool)

This function will determine the number of threads that may be run concurrently in a thread pool.

Parameters:

pool : The thread pool.

Returns: The number of concurrent threads.
Multithreading Level: Safe.

EXPERIMENTAL FUNCTION: subject to change without notice

unsigned int mt_num_processors ()

Get the number of processors available on the system.

Parameters:

Returns: The number of processors available.
Multithreading Level: Unsafe

void mt_launch_job (KThreadPool pool, void (*func) (void *pool_info, void *call_info1, void *call_info2, void *call_info3, void *call_info4, void *thread_info), void *call_info1, void *call_info2, void *call_info3, void *call_info4)

This function will launch a job to a pool of threads, running the job on the first available thread.

Parameters:

pool : The thread pool.
func : The function to execute. The prototype function is mt_PROTO_func
call_info1 : An arbitrary argument to func.
call_info2 : An arbitrary argument to func.
call_info3 : An arbitrary argument to func.
call_info4 : An arbitrary argument to func.

Returns: Nothing.
Multithreading Level: Safe.
Note:

Jobs must not modify any signal actions or masks.

void mt_setlock (KThreadPool pool, flag lock)

This function will lock a thread pool such that no other thread can lock the pool at the same time. This does not prevent other threads from running, nor new jobs from being launched, it merely prevents them from aquiring the lock.

Parameters:

pool : The thread pool to lock.
lock : If TRUE the pool is locked. If FALSE the pool is unlocked and any other threads wishing to lock the pool may do so (one at a time of course).

Returns: Nothing.
Multithreading Level: Safe.

void mt_new_thread_info (KThreadPool pool, void *info, uaddr size)

Parameters:

pool : The thread pool.
info : A pointer to the thread information array. If NULL and size is not 0 then the routine will allocate an array of sufficient size.
size : The size (per thread) in bytes of the thread information. When threads are executing each is guaranteed to have a private working space of this size.

Returns: Nothing. On failure the process aborts.
Multithreading Level: Safe.

void * mt_get_thread_info (KThreadPool pool)

Get the thread information pointer for a pool of threads.

Parameters:

pool : The thread pool.

Returns: A pointer to the thread information array.
Multithreading Level: Safe.

void mt_wait_for_all_jobs (KThreadPool pool)

Wait for all previously launched jobs to complete.

Parameters:

pool : The thread pool.

Returns: Nothing.
Multithreading Level: Safe.

EXPERIMENTAL FUNCTION: subject to change without notice

int mt_get_notify_pipe (KThreadPool pool)

This routine gets the read-end of the notification pipe for a thread pool. If the pipe does not yet exist, it is created. Every time a job completes, an unsigned integer is written to the write-end of the pipe (if it exists). The value if the integer is equal to the thread index.

Parameters:

pool : The thread pool.

Returns: The read-end of the pipe. On failure the process aborts.
Multithreading Level: Safe.
Note:

Once the pipe is created/gotten (and it has not been disabled by mt_disable_notify_pipe, the notification bytes must be consumed, otherwise threads in the pool will eventually become deadlocked.

EXPERIMENTAL FUNCTION: subject to change without notice

void mt_disable_notify_pipe (KThreadPool pool)

Disable the notification pipe.

Parameters:

Returns: Nothing.
Multithreading Level: Safe.

Prototype Functions

void mt_PROTO_func (void *pool_info, void *call_info1, void *call_info2, void *call_info3, void *call_info4, void *thread_info)

Perform a job.

Parameters:

pool_info : The arbitrary pool information pointer.
call_info1 : The first arbitrary call information pointer.
call_info2 : The second arbitrary call information pointer.
call_info3 : The third arbitrary call information pointer.
call_info4 : The fourth arbitrary call information pointer.
thread_info : A pointer to arbitrary, per thread, information. This information is private to the thread.

Returns: Nothing.
Multithreading Level: Unsafe

Back to Karma Home Page

Contact: Richard Gooch
Web Development: Ariel Internet Services