JobQueueInterface Class Reference

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

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 JobQueueInterfaceGetDestinationQueue ()
 
static MAXON_METHOD Result< void > SetDestinationQueue (JobQueueInterface *queue)
 
static MAXON_METHOD JobQueueInterfaceGetMainThreadQueue ()
 
static MAXON_METHOD ServiceIOJobQueueInterfaceGetServiceIOQueue ()
 

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]allocLocationSource location.
[in]typeQueue type.
[in]threadCntThe number of threads used by the queue.
[in]modeScheduling options for the queue. Most of the time there's no need to specify something else than JOBQUEUEMODE::DEFAULT.
[in]nameThe queue name.
[out]ownerIdUsed 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 = LIMITInt >::MAX 
)
static

Returns the number of threads to be used. THREADSAFE.

Parameters
[in]queueQueue interface pointer or JOBQUEUE_CURRENT, JOBQUEUE_NONE.
[in]maxWaitSessionLevelPrivate: 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]ownerIdOwner 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]ownerIdOwner id of the queue (only the owner is allowed to cancel a 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]queueThe 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).