Home --> Documentations --> PJLIB Reference

Macros | Typedefs | Enumerations | Functions

Macros

#define PJ_THREAD_DESC_SIZE   (64)
 
#define PJ_CHECK_STACK()
 
#define pj_thread_get_stack_max_usage(thread)   0
 
#define pj_thread_get_stack_info(thread, f, l)   (*(f)="",*(l)=0)
 

Typedefs

typedef long pj_thread_desc [(64)]
 

Enumerations

enum  pj_thread_create_flags { PJ_THREAD_SUSPENDED = 1 }
 

Functions

typedef int (PJ_THREAD_FUNC pj_thread_proc)(void *)
 
pj_uint32_t pj_getpid (void)
 
pj_status_t pj_thread_create (pj_pool_t *pool, const char *thread_name, pj_thread_proc *proc, void *arg, pj_size_t stack_size, unsigned flags, pj_thread_t **thread)
 
pj_status_t pj_thread_register (const char *thread_name, pj_thread_desc desc, pj_thread_t **thread)
 
pj_bool_t pj_thread_is_registered (void)
 
int pj_thread_get_prio (pj_thread_t *thread)
 
pj_status_t pj_thread_set_prio (pj_thread_t *thread, int prio)
 
int pj_thread_get_prio_min (pj_thread_t *thread)
 
int pj_thread_get_prio_max (pj_thread_t *thread)
 
void * pj_thread_get_os_handle (pj_thread_t *thread)
 
const char * pj_thread_get_name (pj_thread_t *thread)
 
pj_status_t pj_thread_resume (pj_thread_t *thread)
 
pj_thread_tpj_thread_this (void)
 
pj_status_t pj_thread_join (pj_thread_t *thread)
 
pj_status_t pj_thread_destroy (pj_thread_t *thread)
 
pj_status_t pj_thread_sleep (unsigned msec)
 

Detailed Description

This module provides multithreading API.

Examples

For examples, please see:

Macro Definition Documentation

#define PJ_CHECK_STACK ( )

PJ_CHECK_STACK() macro is used to check the sanity of the stack. The OS implementation may check that no stack overflow occurs, and it also may collect statistic about stack usage.

#define PJ_THREAD_DESC_SIZE   (64)

Size of thread struct.

#define pj_thread_get_stack_info (   thread,
  f,
 
)    (*(f)="",*(l)=0)
#define pj_thread_get_stack_max_usage (   thread)    0

Typedef Documentation

typedef long pj_thread_desc[(64)]

Thread structure, to thread's state when the thread is created by external or native API.

Enumeration Type Documentation

Thread creation flags:

  • PJ_THREAD_SUSPENDED: specify that the thread should be created suspended.

Function Documentation

typedef int ( PJ_THREAD_FUNC  pj_thread_proc)

Type of thread entry function.

Referenced by pj_math_stat_update().

pj_uint32_t pj_getpid ( void  )

Get process ID.

Returns
process ID.
pj_status_t pj_thread_create ( pj_pool_t pool,
const char *  thread_name,
pj_thread_proc *  proc,
void *  arg,
pj_size_t  stack_size,
unsigned  flags,
pj_thread_t **  thread 
)

Create a new thread.

Parameters
poolThe memory pool from which the thread record will be allocated from.
thread_nameThe optional name to be assigned to the thread.
procThread entry function.
argArgument to be passed to the thread entry function.
stack_sizeThe size of the stack for the new thread, or ZERO or PJ_THREAD_DEFAULT_STACK_SIZE to let the library choose the reasonable size for the stack. For some systems, the stack will be allocated from the pool, so the pool must have suitable capacity.
flagsFlags for thread creation, which is bitmask combination from enum pj_thread_create_flags.
threadPointer to hold the newly created thread.
Returns
PJ_SUCCESS on success, or the error code.
pj_status_t pj_thread_destroy ( pj_thread_t thread)

Destroy thread and release resources allocated for the thread. However, the memory allocated for the pj_thread_t itself will only be released when the pool used to create the thread is destroyed.

Parameters
threadThe thread handle.
Returns
zero on success.
const char* pj_thread_get_name ( pj_thread_t thread)

Get thread name.

Parameters
threadThe thread handle.
Returns
Thread name as null terminated string.
void* pj_thread_get_os_handle ( pj_thread_t thread)

Return native handle from pj_thread_t for manipulation using native OS APIs.

Parameters
threadPJLIB thread descriptor.
Returns
Native thread handle. For example, when the backend thread uses pthread, this function will return pointer to pthread_t, and on Windows, this function will return HANDLE.
int pj_thread_get_prio ( pj_thread_t thread)

Get thread priority value for the thread.

Parameters
threadThread handle.
Returns
Thread priority value, or -1 on error.
int pj_thread_get_prio_max ( pj_thread_t thread)

Get the highest priority value available for this thread.

Parameters
threadThread handle.
Returns
Minimum thread priority value, or -1 on error.
int pj_thread_get_prio_min ( pj_thread_t thread)

Get the lowest priority value available for this thread.

Parameters
threadThread handle.
Returns
Minimum thread priority value, or -1 on error.
pj_bool_t pj_thread_is_registered ( void  )

Check if this thread has been registered to PJLIB.

Returns
Non-zero if it is registered.
pj_status_t pj_thread_join ( pj_thread_t thread)

Join thread, and block the caller thread until the specified thread exits. If it is called from within the thread itself, it will return immediately with failure status. If the specified thread has already been dead, or it does not exist, the function will return immediately with successful status.

Parameters
threadThe thread handle.
Returns
PJ_SUCCESS on success.
pj_status_t pj_thread_register ( const char *  thread_name,
pj_thread_desc  desc,
pj_thread_t **  thread 
)

Register a thread that was created by external or native API to PJLIB. This function must be called in the context of the thread being registered. When the thread is created by external function or API call, it must be 'registered' to PJLIB using pj_thread_register(), so that it can cooperate with PJLIB's framework. During registration, some data needs to be maintained, and this data must remain available during the thread's lifetime.

Parameters
thread_nameThe optional name to be assigned to the thread.
descThread descriptor, which must be available throughout the lifetime of the thread.
threadPointer to hold the created thread handle.
Returns
PJ_SUCCESS on success, or the error code.
pj_status_t pj_thread_resume ( pj_thread_t thread)

Resume a suspended thread.

Parameters
threadThe thread handle.
Returns
zero on success.
pj_status_t pj_thread_set_prio ( pj_thread_t thread,
int  prio 
)

Set the thread priority. The priority value must be in the priority value range, which can be retrieved with pj_thread_get_prio_min() and pj_thread_get_prio_max() functions.

Parameters
threadThread handle.
prioNew priority to be set to the thread.
Returns
PJ_SUCCESS on success or the error code.
pj_status_t pj_thread_sleep ( unsigned  msec)

Put the current thread to sleep for the specified miliseconds.

Parameters
msecMiliseconds delay.
Returns
zero if successfull.
pj_thread_t* pj_thread_this ( void  )

Get the current thread.

Returns
Thread handle of current thread.

 


PJLIB Open Source, high performance, small footprint, and very very portable framework
Copyright (C) 2006-2009 Teluu Inc.