NSPR Reference: Chapter 31 Thread Pools
Description: The Sun-Netscape Alliance, a strategic alliance formed by America Online and Sun Microsystems, Inc., is delivering iPlanet e-commerce software and enterprise solutions that enable companies to compete successfully in the Net Economy
Keywords: electronic commerce, ecommerce, ebusiness, e-business, e-commerce, enterprise software, net economy, Netscape, Sun Microsystems, Sun-Netscape Alliance, iPlanet, internet software

NSPR Reference Previous Contents Next

## Chapter 31 Thread Pools

This chapter describes the NSPR API Thread Pools

NOTE: 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
Thread Pool Functions

## Thread Pool Types

`PRJobIoDesc`
`PRJobFn`
`PRThreadPool`
`PRJob`

#### 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`
`PR_QueueJob`
`PR_QueueJob_Read`
`PR_QueueJob_Write`
`PR_QueueJobAccept`
`PR_QueueJob_Connect`
`PR_QueueJob_Timer`
`PR_CancelJob`
`PR_JoinJob`
`PR_ShutdownThreadPool`
`PR_JoinThreadPool`

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

The function has the following 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

Previous Contents Next

Last Updated May 18, 2001