juce::AudioWorkgroup Class Reference

A handle to an audio workgroup, which is a collection of realtime threads working together to produce audio by a common deadline. More...

#include <juce_AudioWorkgroup.h>

Collaboration diagram for juce::AudioWorkgroup:

Public Types
using	Erased = FixedSizeFunction< 64, const WorkgroupProvider *()>

Public Member Functions
	AudioWorkgroup ()=default
	Constructs a disengaged handle that does not represent any workgroup.
	AudioWorkgroup (AudioWorkgroup &&)=default
	Move constructor.
	AudioWorkgroup (const AudioWorkgroup &)
	Copy constructor.
	AudioWorkgroup (Erased e)
size_t	getMaxParallelThreadCount () const
	Returns the recommended maximum number of parallel threads that should join this workgroup.
void	join (WorkgroupToken &token) const
	This method attempts to join the calling thread to this workgroup.
	operator bool () const
	Returns true if and only if this object represents a workgroup.
bool	operator!= (const AudioWorkgroup &other) const
	Inequality operator.
AudioWorkgroup &	operator= (AudioWorkgroup &&)=default
	Move assignment operator.
AudioWorkgroup &	operator= (const AudioWorkgroup &other)
	Copy assignment operator.
bool	operator== (const AudioWorkgroup &other) const
	Equality operator.
void	reset ()
	Disengages this instance so that it no longer represents a workgroup.

Private Member Functions
const WorkgroupProvider *	getWorkgroupProvider () const
void	swap (AudioWorkgroup &other) noexcept

Private Attributes
Erased	erased

Detailed Description

A handle to an audio workgroup, which is a collection of realtime threads working together to produce audio by a common deadline.

You can use this class to join a real-time worker thread to a workgroup. Rather than constructing instances of this class directly, you should use functions like AudioProcessor::audioWorkgroupContextChanged() and AudioIODevice::getWorkgroup() to fetch an engaged workgroup from the system.

The class contains a single method, join(). Call this from your real-time thread to with register this workgroup.

Here's an example of how you might use this class:

Constructor()
{
    startRealtimeThread (Thread::RealtimeOptions{}.withApproximateAudioProcessingTime (samplesPerFrame, sampleRate));
    or
    startRealtimeThread (Thread::RealtimeOptions{}.withProcessingTimeMs (10));
}
 
void Thread::run() override
{
    WorkgroupToken token;
 
    getWorkgroup().join (token);
 
    while (wait (-1) && ! threadShouldExit())
    {
        // If the workgroup has changed, rejoin the workgroup with the same token.
        if (workgroupChanged())
            getWorkgroup().join (token);
 
        // Perform the work here
    }
}
 
void AudioProcessor::processBlock()
{
    workerThread->notify();
}

See also

Thread, AudioProcessor, WorkgroupToken

@tags{Audio}

Member Typedef Documentation

Erased

using juce::AudioWorkgroup::Erased = FixedSizeFunction<64, const WorkgroupProvider*()>

Constructor & Destructor Documentation

AudioWorkgroup() [1/4]

juce::AudioWorkgroup::AudioWorkgroup ( Erased  e )

inlineexplicit

Creates an AudioWorkgroup from a function returning a WorkgroupProvider.

AudioWorkgroup() [2/4]

juce::AudioWorkgroup::AudioWorkgroup ( AudioWorkgroup &&  )

default

Move constructor.

AudioWorkgroup() [3/4]

juce::AudioWorkgroup::AudioWorkgroup

(

const AudioWorkgroup &

)

Copy constructor.

AudioWorkgroup() [4/4]

juce::AudioWorkgroup::AudioWorkgroup ( )

default

Constructs a disengaged handle that does not represent any workgroup.

Member Function Documentation

getMaxParallelThreadCount()

size_t juce::AudioWorkgroup::getMaxParallelThreadCount

(

)

const

Returns the recommended maximum number of parallel threads that should join this workgroup.

This recommendation is based on the workgroup attributes and current hardware, but not on system load. On a very busy system, it may be more effective to use fewer parallel threads.

getWorkgroupProvider()

const WorkgroupProvider * juce::AudioWorkgroup::getWorkgroupProvider ( ) const

inlineprivate

References erased.

join()

void juce::AudioWorkgroup::join

(

WorkgroupToken &

token

)

const

This method attempts to join the calling thread to this workgroup.

If the join operation is successful, the token will be engaged, i.e. its getTokenProvider() function will return non-null.

If the token is already engaged and represents a join to another workgroup, the thread will leave that workgroup before joining the workgroup represented by this object. If the 'token' is already engaged and is passed to the same workgroup, the method will not perform any action.

It's important to note that the lifetime of the token should not exceed the lifetime of the associated thread and must be destroyed on the same thread.

operator bool()

juce::AudioWorkgroup::operator bool ( ) const

explicit

Returns true if and only if this object represents a workgroup.

operator!=()

bool juce::AudioWorkgroup::operator!= ( const AudioWorkgroup &  other ) const

inline

Inequality operator.

References operator==().

operator=() [1/2]

AudioWorkgroup & juce::AudioWorkgroup::operator= ( AudioWorkgroup &&  )

default

Move assignment operator.

operator=() [2/2]

AudioWorkgroup & juce::AudioWorkgroup::operator= ( const AudioWorkgroup &  other )

inline

Copy assignment operator.

References swap().

operator==()

bool juce::AudioWorkgroup::operator==

(

const AudioWorkgroup &

other

)

const

Equality operator.

Referenced by operator!=().

reset()

void juce::AudioWorkgroup::reset ( )

inline

Disengages this instance so that it no longer represents a workgroup.

After this call, operator bool() will return false.

References erased.

swap()

void juce::AudioWorkgroup::swap ( AudioWorkgroup &  other )

inlineprivatenoexcept

References erased.

Referenced by operator=().

Member Data Documentation

erased

Erased juce::AudioWorkgroup::erased

private

Referenced by getWorkgroupProvider(), reset(), and swap().

---

The documentation for this class was generated from the following file:

• juce_AudioWorkgroup.h