#include <jobqueue.h>

Inheritance diagram for JobQueueInterface:

Detailed Description

A JobQueue is used to enqueue and execute jobs. You can specify the priority and the number of its worker threads when calling Init().

Besides multithreading a nice application of the queues is to use them to serialize jobs, e.g. if your multithreaded code has to write results to a non-threadsafe part of the application you do this by creating a queue with just one thread that serializes the write request (this is similar to what happens when you enqueue a job in the main event queue).

Please note that you have to make sure that a queue has executed all jobs before releasing it (the queue can not check that because right after such a check a running dequeued job might enqueue something while the queue would try to delete itself). One way to ensure this is to wait for a master job or group which enqueues all depending groups and jobs. @MAXON_ANNOTATION{refclass=false}

Public Member Functions
MAXON_METHOD Int	GetThreadCount () const

MAXON_METHOD void	Cancel (UInt ownerId)

MAXON_METHOD void	CancelAndWait (UInt ownerId)

MAXON_METHOD void	EnableThreadAffinity (UInt ownerId)

MAXON_METHOD void	AlwaysUseCurrentThread (UInt ownerId)

MAXON_METHOD void	SetIdleSpinTime (UInt ownerId, TimeValue spinTime)

Static Public Member Functions
static MAXON_METHOD Result< JobQueueInterface * >	Alloc (MAXON_SOURCE_LOCATION_DECLARATION, JOBQUEUETYPE type, Int threadCnt, JOBQUEUEMODE mode, const Char name, UInt ownerId=nullptr)

static MAXON_METHOD Int	GetThreadCount (JobQueueInterface *queue, Int maxWaitSessionLevel=LIMIT< Int >::MAX)

static MAXON_METHOD JobQueueInterface *	GetDestinationQueue ()

static MAXON_METHOD Result< void >	SetDestinationQueue (JobQueueInterface *queue)

static MAXON_METHOD JobQueueInterface *	GetMainThreadQueue ()

static MAXON_METHOD ServiceIOJobQueueInterface *	GetServiceIOQueue ()

Private Member Functions
	MAXON_INTERFACE_NONVIRTUAL (JobQueueInterface, MAXON_REFERENCE_NORMAL, "net.maxon.interface.jobqueue")

Member Function Documentation

◆ MAXON_INTERFACE_NONVIRTUAL()

MAXON_INTERFACE_NONVIRTUAL	(	JobQueueInterface	,
		MAXON_REFERENCE_NORMAL	,
		"net.maxon.interface.jobqueue"
	)

private

◆ Alloc()

static MAXON_METHOD Result<JobQueueInterface*> Alloc	(	MAXON_SOURCE_LOCATION_DECLARATION	,
		JOBQUEUETYPE	type,
		Int	threadCnt,
		JOBQUEUEMODE	mode,
		const Char *	name,
		UInt *	ownerId = `nullptr`
	)

static

Creates and initializes a job queue. Do not request more threads than CPU cores are available (use JOBQUEUE_USEMAXIMUMTHREADS to request the maximum thread count or Application::GetMachineInfo() to get that information).

Parameters

[in]	allocLocation	Source location.
[in]	type	Queue type.
[in]	threadCnt	The number of threads used by the queue.
[in]	mode	Scheduling options for the queue. Most of the time there's no need to specify something else than JOBQUEUEMODE::DEFAULT.
[in]	name	The queue name.
[out]	ownerId	Used to return the optional owner id of the queue (can be used for CancelAndWait).

◆ GetThreadCount() [1/2]

MAXON_METHOD Int GetThreadCount ( ) const

Returns the number of threads used for the queue. THREADSAFE.

Returns: Number of threads.

◆ GetThreadCount() [2/2]

static MAXON_METHOD Int GetThreadCount	(	JobQueueInterface *	queue,
		Int	maxWaitSessionLevel = `LIMIT< Int >::MAX`
	)

static

Returns the number of threads to be used. THREADSAFE.

Parameters

[in]	queue	Queue interface pointer or JOBQUEUE_CURRENT, JOBQUEUE_NONE.
[in]	maxWaitSessionLevel	Private: Maximum number of nested Wait() calls.

Returns: Number of threads. Guaranteed to be >= 1 (even for JOBQUEUE_NONE).

◆ Cancel()

MAXON_METHOD void Cancel ( UInt ownerId )

Cancels execution of all jobs in the queue (including jobs which are enqueued after this call). Usually the next step is to release the queue and free all its resources. Only the owner of a queue can cancel it (requires the id returned by Init()). As usual Cancel() will not wait and returns immediately after the cancel condition has been set. THREADSAFE.

Parameters

[in] ownerId Owner id of the queue (only the owner is allowed to cancel a queue).

◆ CancelAndWait()

MAXON_METHOD void CancelAndWait ( UInt ownerId )

Cancels execution of all jobs in the queue (including jobs which are enqueued after this call). Waits until the currently running jobs have finished. Only the owner of a queue can cancel it (requires the id returned by Init()). THREADSAFE.

Parameters

[in] ownerId Owner id of the queue (only the owner is allowed to cancel a queue).

◆ EnableThreadAffinity()

MAXON_METHOD void EnableThreadAffinity ( UInt ownerId )

Enables support for job groups with thread affinity. Only the owner of a queue can enable thread affinity (requires the id returned by Init()). THREADSAFE.

Parameters

[in] ownerId Owner id of the queue.

◆ AlwaysUseCurrentThread()

MAXON_METHOD void AlwaysUseCurrentThread ( UInt ownerId )

Enables using the current thread for EnqueueAndWait even though it belongs to a different queue context (useful for alien threads). Only the owner of a queue can opt in to use the current thread for computations (requires the id returned by Init()). THREADSAFE.

Parameters

[in] ownerId Owner id of the queue.

◆ SetIdleSpinTime()

MAXON_METHOD void SetIdleSpinTime	(	UInt	ownerId,
		TimeValue	spinTime
	)

Allows the owner to specify the idle spin time of a queue. Excessive spin times will be ignored. Only the owner of a queue can modify the idle spin time (requires the id returned by Init()). THREADSAFE.

Parameters

[in] ownerId Owner id of the queue.

◆ GetDestinationQueue()

static MAXON_METHOD JobQueueInterface* GetDestinationQueue ( )

static

Returns the queue being used when you specify JOBQUEUE_CURRENT. Usually the destination queue is the same as the queue of the current thread, but there are exceptions: The main (UI) thread for example belongs to the main thread queue (returned by GetMainThreadQueue()), but it has the default queue as target if you specify JOBQUEUE_CURRENT. Furthermore there are rare cases (backward compatibility) where the destination queue has been modified using SetDestinationQueue(). THREADSAFE.

Returns: Destination queue (guaranteed to be a valid pointer).

◆ SetDestinationQueue()

static MAXON_METHOD Result<void> SetDestinationQueue ( JobQueueInterface * queue )

static

Changes the queue that will be used when you enqueue a job/group from this thread and specify JOBQUEUE_CURRENT. All threads created by the caller from now on will inherit the queue. You must own the thread to call this method. Since all child threads will own the the queue you must make sure it'll be referenced for the whole life time of these threads. Removing a reference before these child threads have finished can result in a crash because the threads will not own the queue or add a reference to it. If you have made sure the queue is not used anymore you can call SetDestinationQueue() and switch back to the previous destination queue. Calling this method from within a job or group will result in an error.

Parameters

[in] queue The queue to be used as JOBQUEUE_CURRENT.

Returns: OK on success.

◆ GetMainThreadQueue()

static MAXON_METHOD JobQueueInterface* GetMainThreadQueue ( )

static

Returns the main thread job queue. If you want to run a job in the main thread's context you can enqueue it specifying this queue. Jobs in the main thread queue will be executed whenever the main thread checks for events. This means execution of a job might be delayed if somebody performs a long blocking polling loop. THREADSAFE.

Returns: Main thread job queue (guaranteed to be a valid pointer).

◆ GetServiceIOQueue()

static MAXON_METHOD ServiceIOJobQueueInterface* GetServiceIOQueue ( )

static

Returns a queue for asynchronous I/O and service jobs. THREADSAFE.

Returns: Service I/O queue (guaranteed to be a valid pointer).

Detailed Description

Public Member Functions

Static Public Member Functions

Private Member Functions

Member Function Documentation

◆ MAXON_INTERFACE_NONVIRTUAL()

◆ Alloc()

◆ GetThreadCount() [1/2]

◆ GetThreadCount() [2/2]

◆ Cancel()

◆ CancelAndWait()

◆ EnableThreadAffinity()

◆ AlwaysUseCurrentThread()

◆ SetIdleSpinTime()

◆ GetDestinationQueue()

◆ SetDestinationQueue()

◆ GetMainThreadQueue()

◆ GetServiceIOQueue()