Loading...
Searching...
No Matches
Threading and concurrency

## 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.
PUBLIC void * | csoundCreateThread (uintptr_t(*threadRoutine)(void *), void *userdata)
| Creates and starts a new thread of execution.
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.
PUBLIC void * | csoundGetCurrentThreadId (void)
| Returns the ID of the currently executing thread, or NULL for failure.
PUBLIC uintptr_t | csoundJoinThread (void *thread)
| Waits until the indicated thread's routine has finished.
PUBLIC void * | csoundCreateThreadLock (void)
| Creates and returns a monitor object, or NULL if not successful.
PUBLIC int | csoundWaitThreadLock (void *lock, size_t milliseconds)
| Waits on the indicated monitor object for the indicated period.
PUBLIC void | csoundWaitThreadLockNoTimeout (void *lock)
| Waits on the indicated monitor object until it is notified.
PUBLIC void | csoundNotifyThreadLock (void *lock)
| Notifies the indicated monitor object.
PUBLIC void | csoundDestroyThreadLock (void *lock)
| Destroys the indicated monitor object.
PUBLIC void * | csoundCreateMutex (int isRecursive)
| Creates and returns a mutex object, or NULL if not successful.
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.
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.
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.
PUBLIC void | csoundDestroyMutex (void *mutex_)
| Destroys the indicated mutex object.
PUBLIC void * | csoundCreateBarrier (unsigned int max)
| Create a Thread Barrier.
PUBLIC int | csoundDestroyBarrier (void *barrier)
| Destroy a Thread Barrier.
PUBLIC int | csoundWaitBarrier (void *barrier)
| Wait on the thread barrier.
PUBLIC void * | csoundCreateCondVar ()
| Creates a conditional variable.
PUBLIC void | csoundCondWait (void *condVar, void *mutex)
| Waits up on a conditional variable and mutex.
PUBLIC void | csoundCondSignal (void *condVar)
| Signals a conditional variable.
PUBLIC void | csoundDestroyCondVar (void *condVar)
| Destroys a conditional variable.
PUBLIC void | csoundSleep (size_t milliseconds)
| Waits for at least the specified number of milliseconds, yielding the CPU to other threads.
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.
PUBLIC void | csoundSpinLock (spin_lock_t *spinlock)
| Locks the spinlock.
PUBLIC int | csoundSpinTryLock (spin_lock_t *spinlock)
| Tries the lock, returns CSOUND_SUCCESS if lock could be acquired, CSOUND_ERROR, otherwise.
PUBLIC void | csoundSpinUnLock (spin_lock_t *spinlock)
| Unlocks the spinlock.

## Detailed Description

## Function Documentation

## csoundCondSignal()

PUBLIC void csoundCondSignal | ( | void * | condVar | ) |

Signals a conditional variable.

References PUBLIC.

## csoundCondWait()

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

Waits up on a conditional variable and mutex.

References PUBLIC.

## 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

References PUBLIC.

## csoundCreateCondVar()

PUBLIC void * csoundCreateCondVar | ( |  | ) |

Creates a conditional variable.

References PUBLIC.

## 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.

References PUBLIC.

## csoundCreateThread()

PUBLIC void * csoundCreateThread | ( | uintptr_t(* | threadRoutine )(void *),
|  | 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.

References PUBLIC.

## csoundCreateThread2()

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.

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

References PUBLIC.

## csoundCreateThreadLock()

PUBLIC void * csoundCreateThreadLock | ( | void |  | ) |

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

The object is initially in signaled (notified) state.

References PUBLIC.

## csoundDestroyBarrier()

PUBLIC int csoundDestroyBarrier | ( | void * | barrier | ) |

Destroy a Thread Barrier.

References PUBLIC.

## csoundDestroyCondVar()

PUBLIC void csoundDestroyCondVar | ( | void * | condVar | ) |

Destroys a conditional variable.

References PUBLIC.

## 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.

References PUBLIC.

## csoundDestroyThreadLock()

PUBLIC void csoundDestroyThreadLock | ( | void * | lock | ) |

Destroys the indicated monitor object.

References PUBLIC.

## 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.

References PUBLIC.

## csoundJoinThread()

PUBLIC uintptr_t csoundJoinThread | ( | void * | thread | ) |

Waits until the indicated thread's routine has finished.

Returns the value returned by the thread routine.

References PUBLIC.

## 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.

References PUBLIC.

## 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.

References PUBLIC.

## csoundNotifyThreadLock()

PUBLIC void csoundNotifyThreadLock | ( | void * | lock | ) |

Notifies the indicated monitor object.

References PUBLIC.

## csoundSetYieldCallback()

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.

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.

References PUBLIC.

## csoundSleep()

PUBLIC void csoundSleep | ( | size_t | milliseconds | ) |

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

References PUBLIC.

## csoundSpinLock()

PUBLIC void csoundSpinLock | ( | spin_lock_t * | spinlock | ) |

Locks the spinlock.

References PUBLIC.

## 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);
}
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,...
csoundSpinLock
PUBLIC void csoundSpinLock(spin_lock_t *spinlock)
Locks the spinlock.

References PUBLIC.

## csoundSpinTryLock()

PUBLIC int csoundSpinTryLock | ( | spin_lock_t * | spinlock | ) |

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

References PUBLIC.

## csoundSpinUnLock()

PUBLIC void csoundSpinUnLock | ( | spin_lock_t * | spinlock | ) |

Unlocks the spinlock.

References PUBLIC.

## 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.

References PUBLIC.

## csoundWaitBarrier()

PUBLIC int csoundWaitBarrier | ( | void * | barrier | ) |

Wait on the thread barrier.

References PUBLIC.

## 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.

References PUBLIC.

## 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.

References PUBLIC.