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
Prototype Functions
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:
This function takes no 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:
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:
This function takes no 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)
Register new thread information for the threads in a pool.
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:
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:
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:
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:
This function takes no 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