Group PJ_THREAD

group PJ_THREAD

This module provides multithreading API.

Defines

PJ_THREAD_DESC_SIZE

Size of thread struct.

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.

pj_thread_get_stack_max_usage(thread)

pj_thread_get_stack_max_usage() for the thread

pj_thread_get_stack_info(thread, f, l)

pj_thread_get_stack_info() for the thread

Typedefs

typedef long pj_thread_desc[(64)]

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

Enums

enum pj_thread_create_flags

Thread creation flags:

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

Values:

PJ_THREAD_SUSPENDED = 1

Functions

typedef int(PJ_THREAD_FUNC pj_thread_proc)

Type of thread entry function.

pj_uint32_t pj_getpid(void)

Get process ID.

Return

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.

Return

PJ_SUCCESS on success, or the error code.

Parameters
  • pool: The memory pool from which the thread record will be allocated from.

  • thread_name: The optional name to be assigned to the thread.

  • proc: Thread entry function.

  • arg: Argument to be passed to the thread entry function.

  • stack_size: The 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.

  • flags: Flags for thread creation, which is bitmask combination from enum pj_thread_create_flags.

  • thread: Pointer to hold the newly created thread.

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.

Return

PJ_SUCCESS on success, or the error code.

Parameters
  • thread_name: The optional name to be assigned to the thread.

  • desc: Thread descriptor, which must be available throughout the lifetime of the thread.

  • thread: Pointer to hold the created thread handle.

pj_bool_t pj_thread_is_registered(void)

Check if this thread has been registered to PJLIB.

Return

Non-zero if it is registered.

int pj_thread_get_prio(pj_thread_t *thread)

Get thread priority value for the thread.

Return

Thread priority value, or -1 on error.

Parameters
  • thread: Thread handle.

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.

Return

PJ_SUCCESS on success or the error code.

Parameters
  • thread: Thread handle.

  • prio: New priority to be set to the thread.

int pj_thread_get_prio_min(pj_thread_t *thread)

Get the lowest priority value available for this thread.

Return

Minimum thread priority value, or -1 on error.

Parameters
  • thread: Thread handle.

int pj_thread_get_prio_max(pj_thread_t *thread)

Get the highest priority value available for this thread.

Return

Minimum thread priority value, or -1 on error.

Parameters
  • thread: Thread handle.

void *pj_thread_get_os_handle(pj_thread_t *thread)

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

Return

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.

Parameters
  • thread: PJLIB thread descriptor.

const char *pj_thread_get_name(pj_thread_t *thread)

Get thread name.

Return

Thread name as null terminated string.

Parameters
  • thread: The thread handle.

pj_status_t pj_thread_resume(pj_thread_t *thread)

Resume a suspended thread.

Return

zero on success.

Parameters
  • thread: The thread handle.

pj_thread_t *pj_thread_this(void)

Get the current thread.

Return

Thread handle of current thread.

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.

Return

PJ_SUCCESS on success.

Parameters
  • thread: The thread handle.

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.

Return

zero on success.

Parameters
  • thread: The thread handle.

pj_status_t pj_thread_sleep(unsigned msec)

Put the current thread to sleep for the specified miliseconds.

Return

zero if successfull.

Parameters
  • msec: Miliseconds delay.