You are currently viewing a snapshot of www.mozilla.org taken on April 21, 2008. Most of this content is highly out of date (some pages haven't been updated since the project began in 1998) and exists for historical purposes only. If there are any pages on this archive site that you think should be added back to www.mozilla.org, please file a bug.

Skip to main content

NSPR Reference

Thread Pools (Chapter 31)

This chapter describes the NSPR API Thread Pools.

This API is a preliminary version in NSPR 4.0 and is subject to change.

Thread pools create and manage threads to provide support for scheduling work (jobs) onto one or more threads. NSPR's thread pool is modeled on the thread pools described by David R. Butenhof in Programming with POSIX Threads (Addison-Wesley, 1997).

Thread Pool Types

PRJobIoDesc

Syntax
#include <prtpool.h>

typedef struct PRJobIoDesc {
   PRFileDesc *socket;
   PRErrorCode error;
   PRIntervalTime timeout;
} PRJobIoDesc;
Description

PRJobFn

Syntax
#include <prtpool.h>

typedev void (PR_CALLBACK *PRJobFn)(void *arg);
Description

PRThreadPool

Syntax
#include <prtpool.h>
Description

PRJob

Syntax
#include <prtpool.h>
Description

Thread Pool Functions

PR_CreateThreadPool

Creates a pool of thread for scheduling jobs.

Syntax
#include <prtpool.h>

NSPR_API(PRThreadPool *)
PR_CreateThreadPool(
   PRInt32 initial_threads,
   PRInt32 max_threads,
   PRUint32 stacksize
);
Parameters

The function has the following parameters:

initial_threads
The number of threads to be created within this thread pool.
max_threads
The limit on the number of threads that will be created to server the thread pool.
stacksize
Size of the stack allocated to each thread in the thread.
Returns

Pointer to a PRThreadPool structure or NULL on error.

Description

PR_QueueJob

Queues a job to a thread pool for execution.

Syntax
#include <prtpool.h>

NSPR_API(PRJob *)
PR_QueueJob(
   PRThreadPool *tpool,
   PRJobFn fn,
   void *arg,
   PRBool joinable
);
Parameters
tpool
A pointer to a PRThreadPool structure previously created by a call to PR_CreateThreadPool.
fn
The function to be executed when the job is executed.
arg
A pointer to an argument passed to fn.
joinable
If PR_TRUE, the job is joinable. If PR_FALSE, the job is not joinable. See PR_JoinJob.
Returns

Pointer to a PRJob structure or NULL on error.

Description

PR_QueueJob_Read

Causes a job to be queued when a socket becomes readable.

Syntax
#include <prtpool.h>

NSPR_API(PRJob *)
PR_QueueJob_Read(
   PRThreadPool *tpool,
   PRJobIoDesc *iod,
   PRJobFn fn,
   void *arg,
   PRBool joinable
);
Parameters

The function has the following parameters:

tpool
A pointer to a PRThreadPool structure previously created by a call to PR_CreateThreadPool.
iod
A pointer to a PRJobIoDesc structure.
fn
The function to be executed when the job is executed.
arg
A pointer to an argument passed to fn.
joinable
If PR_TRUE, the job is joinable. If PR_FALSE, the job is not joinable. See PR_JoinJob.
Returns

Pointer to a PRJob structure or NULL on error.

Description

PR_QueueJob_Write

Causes a job to be queued when a socket becomes writable.

Syntax
#include <prtpool.h>

NSPR_API(PRJob *)
PR_QueueJob_Write(
   PRThreadPool *tpool,
   PRJobIoDesc *iod,
   PRJobFn fn,
   void * arg,
   PRBool joinable
);
Parameters

The function has the following parameters:

tpool
A pointer to a PRThreadPool structure previously created by a call to PR_CreateThreadPool.
iod
A pointer to a PRJobIoDesc structure.
fn
The function to be executed when the job is executed.
arg
A pointer to an argument passed to fn.
joinable
If PR_TRUE, the job is joinable. If PR_FALSE, the job is not joinable. See PR_JoinJob.
Returns

Pointer to a PRJob structure or NULL on error.

Description

PR_QueueJobAccept

Causes a job to be queued when a socket has a pending connection.

Syntax
#include <prtpool.h>

NSPR_API(PRJob *)
PR_QueueJob_Accept(
   PRThreadPool *tpool,
   PRJobIoDesc *iod,
   PRJobFn fn,
   void * arg,
   PRBool joinable
);
Parameters

The function has the following parameters:

tpool
A pointer to a PRThreadPool structure previously created by a call to PR_CreateThreadPool.
iod
A pointer to a PRJobIoDesc structure.
fn
The function to be executed when the job is executed.
arg
A pointer to an argument passed to fn.
joinable
If PR_TRUE, the job is joinable. If PR_FALSE, the job is not joinable. See PR_JoinJob.
Returns

Pointer to a PRJob structure or NULL on error.

Description

PR_QueueJob_Connect

Causes a job to be queued when a socket can be connected.

Syntax
#include <prtpool.h>

NSPR_API(PRJob *)
PR_QueueJob_Connect(
   PRThreadPool *tpool,
   PRJobIoDesc *iod,
   const PRNetAddr *addr,
   PRJobFn fn,
   void * arg,
   PRBool joinable
);
Parameters

The function has the following parameters:

tpool
A pointer to a PRThreadPool structure previously created by a call to PR_CreateThreadPool.
iod
A pointer to a PRJobIoDesc structure
addr
Pointer to a PRNetAddr structure for the socket being connected.
fn
The function to be executed when the job is executed.
arg
A pointer to an argument passed to fn.
joinable
If PR_TRUE, the job is joinable. If PR_FALSE, the job is not joinable. See PR_JoinJob.
Returns

Pointer to a PRJob structure or NULL on error.

Description

PR_QueueJob_Timer

Causes a job to be queued when a timer expires.

Syntax
#include <prtpool.h>

NSPR_API(PRJob *)
PR_QueueJob_Timer(
   PRThreadPool *tpool,
   PRIntervalTime timeout,
   PRJobFn fn,
   void * arg,
   PRBool joinable
);
Parameters

The function has the following parameters:

tpool
A pointer to a PRThreadPool structure previously created by a call to PR_CreateThreadPool.
timeout
A value, expressed as a PRIntervalTime, to wait before queuing the job.
fn
The function to be executed when the job is executed.
arg
A pointer to an argument passed to fn.
joinable
If PR_TRUE, the job is joinable. If PR_FALSE, the job is not joinable. See PR_JoinJob.
Returns

Pointer to a PRJob structure or NULL on error.

Description

PR_CancelJob

Causes a previously queued job to be canceled.

Syntax
#include <prtpool.h>

NSPR_API(PRStatus) PR_CancelJob(PRJob *job);
Parameters

The function has the following parameter:

job
A pointer to a PRJob structure returned by a PR_QueueJob function representing the job to be cancelled.
Returns

PRStatus

Description

PR_JoinJob

Blocks the current thread until a job has completed.

Syntax
#include <prtpool.h>

NSPR_API(PRStatus) PR_JoinJob(PRJob *job);
Parameters

The function has the following parameter:

job
A pointer to a PRJob structure returned by a PR_QueueJob function representing the job to be cancelled.
Returns

PRStatus

Description

PR_ShutdownThreadPool

Notifies all threads in a thread pool to terminate.

Syntax
#include <prtpool.h>

NSPR_API(PRStatus) PR_ShutdownThreadPool( PRThreadPool *tpool );
Parameters

The function has the following parameter:

tpool
A pointer to a PRThreadPool structure previously created by a call to PR_CreateThreadPool.
Returns

PRStatus

Description

PR_JoinThreadPool

Waits for all threads in a thread pool to complete, then releases resources allocated to the thread pool.

Syntax
#include <prtpool.h>

NSPR_API(PRStatus) PR_JoinThreadPool( PRThreadPool *tpool );
Parameters

The function has the following parameter:

tpool
A pointer to a PRThreadPool structure previously created by a call to PR_CreateThreadPool.
Returns

PRStatus

Description