Functions
PUBLIC void	csoundSetYieldCallback (CSOUND , int(yieldCallback_)(CSOUND *))
	Called by external software to set a function for checking system events, yielding cpu time for coopertative multitasking, etc. More...

PUBLIC void *	csoundCreateThread (uintptr_t(threadRoutine)(void ), void *userdata)
	Creates and starts a new thread of execution. More...

PUBLIC void *	csoundCreateThread2 (uintptr_t(threadRoutine)(void ), unsigned int stack, void *userdata)
	Creates and starts a new thread of execution with a user-defined stack size. More...

PUBLIC void *	csoundGetCurrentThreadId (void)
	Returns the ID of the currently executing thread, or NULL for failure. More...

PUBLIC uintptr_t	csoundJoinThread (void *thread)
	Waits until the indicated thread's routine has finished. More...

PUBLIC void *	csoundCreateThreadLock (void)
	Creates and returns a monitor object, or NULL if not successful. More...

PUBLIC int	csoundWaitThreadLock (void *lock, size_t milliseconds)
	Waits on the indicated monitor object for the indicated period. More...

PUBLIC void	csoundWaitThreadLockNoTimeout (void *lock)
	Waits on the indicated monitor object until it is notified. More...

PUBLIC void	csoundNotifyThreadLock (void *lock)
	Notifies the indicated monitor object. More...

PUBLIC void	csoundDestroyThreadLock (void *lock)
	Destroys the indicated monitor object. More...

PUBLIC void *	csoundCreateMutex (int isRecursive)
	Creates and returns a mutex object, or NULL if not successful. More...

PUBLIC void	csoundLockMutex (void *mutex_)
	Acquires the indicated mutex object; if it is already in use by another thread, the function waits until the mutex is released by the other thread. More...

PUBLIC int	csoundLockMutexNoWait (void *mutex_)
	Acquires the indicated mutex object and returns zero, unless it is already in use by another thread, in which case a non-zero value is returned immediately, rather than waiting until the mutex becomes available. More...

PUBLIC void	csoundUnlockMutex (void *mutex_)
	Releases the indicated mutex object, which should be owned by the current thread, otherwise the operation of this function is undefined. More...

PUBLIC void	csoundDestroyMutex (void *mutex_)
	Destroys the indicated mutex object. More...

PUBLIC void *	csoundCreateBarrier (unsigned int max)
	Create a Thread Barrier. More...

PUBLIC int	csoundDestroyBarrier (void *barrier)
	Destroy a Thread Barrier. More...

PUBLIC int	csoundWaitBarrier (void *barrier)
	Wait on the thread barrier. More...

PUBLIC void *	csoundCreateCondVar ()
	Creates a conditional variable. More...

PUBLIC void	csoundCondWait (void condVar, void mutex)
	Waits up on a conditional variable and mutex. More...

PUBLIC void	csoundCondSignal (void *condVar)
	Signals a conditional variable. More...

PUBLIC void	csoundDestroyCondVar (void *condVar)
	Destroys a conditional variable. More...

PUBLIC void	csoundSleep (size_t milliseconds)
	Waits for at least the specified number of milliseconds, yielding the CPU to other threads. More...

PUBLIC int	csoundSpinLockInit (spin_lock_t *spinlock)
	If the spinlock is not locked, lock it and return; if is is locked, wait until it is unlocked, then lock it and return. More...

PUBLIC void	csoundSpinLock (spin_lock_t *spinlock)
	Locks the spinlock. More...

PUBLIC int	csoundSpinTryLock (spin_lock_t *spinlock)
	Tries the lock, returns CSOUND_SUCCESS if lock could be acquired, CSOUND_ERROR, otherwise. More...

PUBLIC void	csoundSpinUnLock (spin_lock_t *spinlock)
	Unlocks the spinlock. More...

Detailed Description

Function Documentation

◆ csoundCondSignal()

PUBLIC void csoundCondSignal ( void * condVar )

Signals a conditional variable.

◆ csoundCondWait()

PUBLIC void csoundCondWait	(	void *	condVar,
		void *	mutex
	)

Waits up on a conditional variable and mutex.

◆ csoundCreateBarrier()

PUBLIC void* csoundCreateBarrier ( unsigned int max )

Create a Thread Barrier.

Max value parameter should be equal to number of child threads using the barrier plus one for the master thread

◆ csoundCreateCondVar()

PUBLIC void* csoundCreateCondVar ( )

Creates a conditional variable.

◆ csoundCreateMutex()

PUBLIC void* csoundCreateMutex ( int isRecursive )

Creates and returns a mutex object, or NULL if not successful.

Mutexes can be faster than the more general purpose monitor objects returned by csoundCreateThreadLock() on some platforms, and can also be recursive, but the result of unlocking a mutex that is owned by another thread or is not locked is undefined. If 'isRecursive' is non-zero, the mutex can be re-locked multiple times by the same thread, requiring an equal number of unlock calls; otherwise, attempting to re-lock the mutex results in undefined behavior. Note: the handles returned by csoundCreateThreadLock() and csoundCreateMutex() are not compatible.

◆ csoundCreateThread()

PUBLIC void* csoundCreateThread	(	uintptr_t()(void )	threadRoutine,
		void *	userdata
	)

Creates and starts a new thread of execution.

Returns an opaque pointer that represents the thread on success, or NULL for failure. The userdata pointer is passed to the thread routine.

◆ csoundCreateThread2()

PUBLIC void* csoundCreateThread2	(	uintptr_t()(void )	threadRoutine,
		unsigned int	stack,
		void *	userdata
	)

Creates and starts a new thread of execution with a user-defined stack size.

Returns an opaque pointer that represents the thread on success, or NULL for failure. The userdata pointer is passed to the thread routine.

◆ csoundCreateThreadLock()

PUBLIC void* csoundCreateThreadLock ( void )

Creates and returns a monitor object, or NULL if not successful.

The object is initially in signaled (notified) state.

◆ csoundDestroyBarrier()

PUBLIC int csoundDestroyBarrier ( void * barrier )

Destroy a Thread Barrier.

◆ csoundDestroyCondVar()

PUBLIC void csoundDestroyCondVar ( void * condVar )

Destroys a conditional variable.

◆ csoundDestroyMutex()

PUBLIC void csoundDestroyMutex ( void * mutex_ )

Destroys the indicated mutex object.

Destroying a mutex that is currently owned by a thread results in undefined behavior.

◆ csoundDestroyThreadLock()

PUBLIC void csoundDestroyThreadLock ( void * lock )

Destroys the indicated monitor object.

◆ csoundGetCurrentThreadId()

PUBLIC void* csoundGetCurrentThreadId ( void )

Returns the ID of the currently executing thread, or NULL for failure.

NOTE: The return value can be used as a pointer to a thread object, but it should not be compared as a pointer. The pointed to values should be compared, and the user must free the pointer after use.

◆ csoundJoinThread()

PUBLIC uintptr_t csoundJoinThread ( void * thread )

Waits until the indicated thread's routine has finished.

Returns the value returned by the thread routine.

◆ csoundLockMutex()

PUBLIC void csoundLockMutex ( void * mutex_ )

Acquires the indicated mutex object; if it is already in use by another thread, the function waits until the mutex is released by the other thread.

◆ csoundLockMutexNoWait()

PUBLIC int csoundLockMutexNoWait ( void * mutex_ )

Acquires the indicated mutex object and returns zero, unless it is already in use by another thread, in which case a non-zero value is returned immediately, rather than waiting until the mutex becomes available.

Note: this function may be unimplemented on Windows.

◆ csoundNotifyThreadLock()

PUBLIC void csoundNotifyThreadLock ( void * lock )

Notifies the indicated monitor object.

◆ csoundSetYieldCallback()

PUBLIC void csoundSetYieldCallback	(	CSOUND *	,
		int()(CSOUND )	yieldCallback_
	)

Called by external software to set a function for checking system events, yielding cpu time for coopertative multitasking, etc.

This function is optional. It is often used as a way to 'turn off' Csound, allowing it to exit gracefully. In addition, some operations like utility analysis routines are not reentrant and you should use this function to do any kind of updating during the operation. Returns an 'OK to continue' boolean.

◆ csoundSleep()

PUBLIC void csoundSleep ( size_t milliseconds )

Waits for at least the specified number of milliseconds, yielding the CPU to other threads.

◆ csoundSpinLock()

PUBLIC void csoundSpinLock ( spin_lock_t * spinlock )

Locks the spinlock.

◆ csoundSpinLockInit()

PUBLIC int csoundSpinLockInit ( spin_lock_t * spinlock )

If the spinlock is not locked, lock it and return; if is is locked, wait until it is unlocked, then lock it and return.

Uses atomic compare and swap operations that are safe across processors and safe for out of order operations, and which are more efficient than operating system locks. Use spinlocks to protect access to shared data, especially in functions that do little more than read or write such data, for example:

static spin_lock_t lock = SPINLOCK_INIT;
csoundSpinLockInit(&lock);
void write(size_t frames, int* signal)
{
  csoundSpinLock(&lock);
  for (size_t frame = 0; i < frames; frame++) {
    global_buffer[frame] += signal[frame];
  }
  csoundSpinUnlock(&lock);
}

◆ csoundSpinTryLock()

PUBLIC int csoundSpinTryLock ( spin_lock_t * spinlock )

Tries the lock, returns CSOUND_SUCCESS if lock could be acquired, CSOUND_ERROR, otherwise.

◆ csoundSpinUnLock()

PUBLIC void csoundSpinUnLock ( spin_lock_t * spinlock )

Unlocks the spinlock.

◆ csoundUnlockMutex()

PUBLIC void csoundUnlockMutex ( void * mutex_ )

Releases the indicated mutex object, which should be owned by the current thread, otherwise the operation of this function is undefined.

A recursive mutex needs to be unlocked as many times as it was locked previously.

◆ csoundWaitBarrier()

PUBLIC int csoundWaitBarrier ( void * barrier )

Wait on the thread barrier.

◆ csoundWaitThreadLock()

PUBLIC int csoundWaitThreadLock	(	void *	lock,
		size_t	milliseconds
	)

Waits on the indicated monitor object for the indicated period.

The function returns either when the monitor object is notified, or when the period has elapsed, whichever is sooner; in the first case, zero is returned. If 'milliseconds' is zero and the object is not notified, the function will return immediately with a non-zero status.

◆ csoundWaitThreadLockNoTimeout()

PUBLIC void csoundWaitThreadLockNoTimeout ( void * lock )

Waits on the indicated monitor object until it is notified.

This function is similar to csoundWaitThreadLock() with an infinite wait time, but may be more efficient.

Functions