127 lines
4.3 KiB
C
127 lines
4.3 KiB
C
/* This Source Code Form is subject to the terms of the Mozilla Public
|
|
* License, v. 2.0. If a copy of the MPL was not distributed with this
|
|
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
|
|
|
|
#ifndef _CPR_THREADS_H_
|
|
#define _CPR_THREADS_H_
|
|
|
|
#include "cpr_types.h"
|
|
|
|
__BEGIN_DECLS
|
|
|
|
/**
|
|
* @typedef void *cprThread_t
|
|
* Define handle for threads
|
|
*/
|
|
typedef void *cprThread_t;
|
|
|
|
/**
|
|
* @struct cpr_thread_t
|
|
* System thread information needed to hide OS differences in implementation.
|
|
* To use threads, the application code may pass in a name to the
|
|
* create function for threads. CPR does not use this field, it is
|
|
* solely for the convenience of the application and to aid in debugging.
|
|
* Upon an application calling the init routine, CPR will malloc the
|
|
* memory for a thread, set the handlePtr or handleInt as appropriate
|
|
* and return a pointer to the thread structure.
|
|
*/
|
|
typedef struct {
|
|
const char *name;
|
|
uint32_t threadId;
|
|
union {
|
|
void *handlePtr;
|
|
uint64_t handleInt;
|
|
} u;
|
|
} cpr_thread_t;
|
|
|
|
/**
|
|
* Thread start routine signature
|
|
*/
|
|
typedef void *(*cprThreadStartRoutine)(void *data);
|
|
|
|
/* Function prototypes */
|
|
|
|
/**
|
|
* cprCreateThread
|
|
*
|
|
* @brief Create a thread
|
|
*
|
|
* The cprCreateThread function creates another execution thread within the
|
|
* current process. If the input parameter "name" is present, then this is used
|
|
* for debugging purposes. The startRoutine is the address of the function where
|
|
* the thread execution begins. The start routine prototype is defined as
|
|
* follows
|
|
* @code
|
|
* int32_t (*cprThreadStartRoutine)(void* data)
|
|
* @endcode
|
|
*
|
|
* @param[in] name - name of the thread created (optional)
|
|
* @param[in] startRoutine - function where thread execution begins
|
|
* @param[in] stackSize - size of the thread's stack (IGNORED)
|
|
* @param[in] priority - thread's execution priority (IGNORED)
|
|
* @param[in] data - parameter to pass to startRoutine
|
|
*
|
|
* Return Value: Thread handle or NULL if creation failed.
|
|
*/
|
|
cprThread_t cprCreateThread(const char *name,
|
|
cprThreadStartRoutine startRoutine,
|
|
uint16_t stackSize,
|
|
uint16_t priority,
|
|
void *data);
|
|
|
|
|
|
/**
|
|
* cprDestroyThread
|
|
*
|
|
* @brief Destroys the thread passed in.
|
|
*
|
|
* The cprDestroyThread function is called to destroy a thread. The thread
|
|
* parameter may be any valid thread including the calling thread itself.
|
|
*
|
|
* @param[in] thread - thread to destroy.
|
|
*
|
|
* @return CPR_SUCCESS or CPR_FAILURE. errno should be set for FAILURE case.
|
|
*
|
|
* @note In Linux there will never be a success indication as the
|
|
* calling thread will have been terminated.
|
|
*/
|
|
cprRC_t cprDestroyThread(cprThread_t thread);
|
|
|
|
/**
|
|
* cprAdjustRelativeThreadPriority
|
|
*
|
|
* @brief The function sets the relative thread priority up or down by the given value.
|
|
*
|
|
* pSIPCC specific important notes:
|
|
* This function is used by pSIPCC to set up the priority for its threads.
|
|
* When pSIPCC creates threads, it requests default priority
|
|
* and then subsequently calls this function to adjust the level to desired
|
|
* value.
|
|
* relPri ranges from -20 (Maximum priority) to +19 (Minimum priority).
|
|
* The relPri values are normalized to Linux Nice levels. This implies
|
|
* that these values must be mapped to a range or values of your OS.
|
|
* For example:
|
|
* if your OS supports thread priorities ranging from 1 to 10 then you
|
|
* could do a simple linear mapping of 40 nice values to 10 values
|
|
* by mapping 1 to 19 and 10 to -20 and so on.
|
|
* The mapping is completely determined by your implementation below.
|
|
* Note that pSIPCC threads must run at a sufficiently higher priority to
|
|
* provide proper signaling cut through times.
|
|
* obviously, signaling cut through ultimately affects the media cut through.
|
|
* pSIPCC also uses virtual timers which require sufficiently high priority
|
|
* to provide accurate timeout behavior.
|
|
* A general guideline is to map the relPri passed such that it is somewhere
|
|
* in between the non critical threads and highly critical threads such as
|
|
* media or timer processing on your system.
|
|
*
|
|
* @param[in] relPri - normalized relative Priority of the thread [-20,+19]
|
|
*
|
|
* @return CPR_SUCCESS or CPR_FAILURE
|
|
*/
|
|
cprRC_t cprAdjustRelativeThreadPriority(int relPri);
|
|
|
|
|
|
__END_DECLS
|
|
|
|
#endif
|