pa_unix_util.c File Reference

#include <pthread.h>
#include <unistd.h>
#include <stdlib.h>
#include <time.h>
#include <sys/time.h>
#include <assert.h>
#include <string.h>
#include <math.h>
#include <errno.h>
#include "pa_util.h"
#include "pa_unix_util.h"
#include "pa_debugprint.h"

Functions
void *	PaUtil_AllocateZeroInitializedMemory (long size)
void	PaUtil_FreeMemory (void *block)
int	PaUtil_CountCurrentlyAllocatedBlocks (void)
void	Pa_Sleep (long msec)
void	PaUtil_InitializeClock (void)
PaTime	PaUtil_GetTime (void)
PaError	PaUtil_InitializeThreading (PaUtilThreading *threading)
void	PaUtil_TerminateThreading (PaUtilThreading *threading)
PaError	PaUtil_StartThreading (PaUtilThreading *threading, void *(*threadRoutine)(void *), void *data)
PaError	PaUtil_CancelThreading (PaUtilThreading *threading, int wait, PaError *exitResult)
PaError	PaUnixThreading_Initialize (void)
PaError	PaUnixThread_New (PaUnixThread *self, void *(*threadFunc)(void *), void *threadArg, PaTime waitForChild, int rtSched)
PaError	PaUnixThread_Terminate (PaUnixThread *self, int wait, PaError *exitResult)
PaError	PaUnixThread_PrepareNotify (PaUnixThread *self)
PaError	PaUnixThread_NotifyParent (PaUnixThread *self)
int	PaUnixThread_StopRequested (PaUnixThread *self)
PaError	PaUnixMutex_Initialize (PaUnixMutex *self)
PaError	PaUnixMutex_Terminate (PaUnixMutex *self)
PaError	PaUnixMutex_Lock (PaUnixMutex *self)
PaError	PaUnixMutex_Unlock (PaUnixMutex *self)

Variables
pthread_t	paUnixMainThread = 0

Function Documentation

Pa_Sleep()

void Pa_Sleep

(

long

msec

)

Put the caller to sleep for at least 'msec' milliseconds. This function is provided only as a convenience for authors of portable code (such as the tests and examples in the PortAudio distribution.)

The function may sleep longer than requested so don't rely on this for accurate musical timing.

PaUnixMutex_Initialize()

PaError PaUnixMutex_Initialize

(

PaUnixMutex *

self

)

References PaUnixMutex::mtx, PA_ASSERT_CALL, and paNoError.

Referenced by PaUnixThread_New().

PaUnixMutex_Lock()

PaError PaUnixMutex_Lock

(

PaUnixMutex *

self

)

Lock mutex.

We're disabling thread cancellation while the thread is holding a lock, so mutexes are properly unlocked at termination time.

References PaUnixMutex::mtx, PA_ENSURE_SYSTEM, and paNoError.

Referenced by PaUnixThread_New(), PaUnixThread_NotifyParent(), and PaUnixThread_PrepareNotify().

PaUnixMutex_Terminate()

PaError PaUnixMutex_Terminate

(

PaUnixMutex *

self

)

References PaUnixMutex::mtx, PA_ASSERT_CALL, and paNoError.

Referenced by PaUnixThread_Terminate().

PaUnixMutex_Unlock()

PaError PaUnixMutex_Unlock

(

PaUnixMutex *

self

)

Unlock mutex.

Thread cancellation is enabled again after the mutex is properly unlocked.

References PaUnixMutex::mtx, PA_ENSURE_SYSTEM, and paNoError.

Referenced by PaUnixThread_New(), and PaUnixThread_NotifyParent().

PaUnixThread_New()

PaError PaUnixThread_New	(	PaUnixThread *	self,
		void *(*	threadFunc )(void *),
		void *	threadArg,
		PaTime	waitForChild,
		int	rtSched )

Spawn a thread.

Intended for spawning the callback thread from the main thread. This function can even block (for a certain time or indefinitely) until notified by the callback thread (using PaUnixThread_NotifyParent), which can be useful in order to make sure that callback has commenced before returning from Pa_StartStream.

Parameters

threadFunc	The function to be executed in the child thread.
waitForChild	If not 0, wait for child thread to call PaUnixThread_NotifyParent. Less than 0 means wait for ever, greater than 0 wait for the specified time.
rtSched	Enable realtime scheduling?

Returns

: If timed out waiting on child, paTimedOut.

References PaUnixThread::cond, PaUnixThread::condClockId, PaUnixMutex::mtx, PaUnixThread::mtx, PA_ASSERT_CALL, PA_DEBUG, PA_ENSURE, PA_ENSURE_SYSTEM, PA_MIN, PA_UNLESS, paInternalError, paNoError, PaPthreadUtil_GetTime(), PaPthreadUtil_NegotiateCondAttrClock(), PaUnixThread::parentWaiting, paTimedOut, PaUnixMutex_Initialize(), PaUnixMutex_Lock(), PaUnixMutex_Unlock(), PaUnixThread_Terminate(), PaUtil_GetTime(), and PaUnixThread::thread.

PaUnixThread_NotifyParent()

PaError PaUnixThread_NotifyParent

(

PaUnixThread *

self

)

Notify waiting parent thread.

Returns

: If parent timed out waiting, paTimedOut. If parent was never waiting, paInternalError.

References PaUnixThread::cond, PaUnixThread::locked, PaUnixThread::mtx, PA_ENSURE, PA_UNLESS, paInternalError, paNoError, PaUnixThread::parentWaiting, PaUnixMutex_Lock(), and PaUnixMutex_Unlock().

PaUnixThread_PrepareNotify()

PaError PaUnixThread_PrepareNotify

(

PaUnixThread *

self

)

Prepare to notify waiting parent thread.

An internal lock must be held before the parent is notified in PaUnixThread_NotifyParent, call this to acquire it beforehand.

Returns

: If parent is not waiting, paInternalError.

References PaUnixThread::locked, PaUnixThread::mtx, PA_ENSURE, PA_UNLESS, paInternalError, paNoError, PaUnixThread::parentWaiting, and PaUnixMutex_Lock().

PaUnixThread_StopRequested()

int PaUnixThread_StopRequested

(

PaUnixThread *

self

)

Has the parent thread requested this thread to stop?

References PaUnixThread::stopRequested.

PaUnixThread_Terminate()

PaError PaUnixThread_Terminate	(	PaUnixThread *	self,
		int	wait,
		PaError *	exitResult )

Terminate thread.

Parameters

wait	If true, request that background thread stop and wait until it does, else cancel it.
exitResult	If non-null this will upon return contain the exit status of the thread.

References PaUnixThread::cond, PaUnixThread::mtx, PA_ASSERT_CALL, PA_DEBUG, PA_ENSURE_SYSTEM, paNoError, PaUnixMutex_Terminate(), PaUnixThread::stopRequested, and PaUnixThread::thread.

Referenced by PaUnixThread_New().

PaUnixThreading_Initialize()

PaError PaUnixThreading_Initialize

(

void

)

Initialize global threading state.

References paNoError, and paUnixMainThread.

Referenced by PaAlsa_Initialize(), and PaAsiHpi_Initialize().

PaUtil_AllocateZeroInitializedMemory()

void * PaUtil_AllocateZeroInitializedMemory

(

long

size

)

Allocate size bytes of zero-initialized memory. Guaranteed to be aligned to a FIXME byte boundary.

PaUtil_CancelThreading()

PaError PaUtil_CancelThreading	(	PaUtilThreading *	threading,
		int	wait,
		PaError *	exitResult )

References PaUtilThreading::callbackThread, and paNoError.

PaUtil_CountCurrentlyAllocatedBlocks()

int PaUtil_CountCurrentlyAllocatedBlocks

(

void

)

Return the number of currently allocated blocks. This function can be used for detecting memory leaks.

Note

Allocations will only be tracked if PA_TRACK_MEMORY is #defined. If it isn't, this function will always return 0.

PaUtil_FreeMemory()

void PaUtil_FreeMemory

(

void *

block

)

Release block allocated by PaUtil_AllocateZeroInitializedMemory() if block is non-NULL. block may be NULL

PaUtil_GetTime()

PaTime PaUtil_GetTime

(

void

)

Return the system time in seconds. Used to implement CPU load functions

Note

Do not make assumptions about which underlying clock is used to implement PaUtil_GetTime, or use the current implementation as a guide. Do not use this function when a specific clock is required (e.g. when using platform APIs such as pthreads). If you need to use a specific clock, use a native API that returns that clock.

See also

PaUtil_InitializeClock

Referenced by PaUnixThread_New().

PaUtil_InitializeClock()

void PaUtil_InitializeClock

(

void

)

Initialize the clock used by PaUtil_GetTime(). Call this before calling PaUtil_GetTime.

See also

PaUtil_GetTime

PaUtil_InitializeThreading()

PaError PaUtil_InitializeThreading

(

PaUtilThreading *

threading

)

References paNoError.

PaUtil_StartThreading()

PaError PaUtil_StartThreading	(	PaUtilThreading *	threading,
		void *(*	threadRoutine )(void *),
		void *	data )

References PaUtilThreading::callbackThread, and paNoError.

PaUtil_TerminateThreading()

void PaUtil_TerminateThreading

(

PaUtilThreading *

threading

)

Variable Documentation

paUnixMainThread

pthread_t paUnixMainThread = 0

Referenced by PaUnixThreading_Initialize().