IDXTaskManager Interface

The IDXTaskManager interface enables you to configure the task manager to specify the thread pool size and the thread concurrency limit. The task manager is a generic service used to schedule and execute caller-defined tasks. It automatically breaks a transform task into threads and manages their completion, which improves the efficiency of the transform.

The default thread pool size is two threads per processor, and the default concurrency limit is one thread per processor. The default implementation uses input/output completion ports on Microsoft® Windows® NT to optimize processor utilization.

IDXTaskManager Methods

GetConcurrencyLimit Retrieves the number of threads allowed to execute on a single processor at a given time.

GetThreadPoolSize Retrieves the number of threads in the thread pool.

QueryNumProcessors Retrieves the number of processors installed in the system.

ScheduleTasks Defines a set of tasks to execute.

SetConcurrencyLimit Defines the number of threads that can execute from a thread pool at a given time.

SetThreadPoolSize Specifies the number of threads that should be created and made available to execute tasks.

TerminateRequest Terminates a task based on its request ID value that was used when it was scheduled.

TerminateTasks Terminates a set of tasks previously scheduled by the task manager.

IDXTaskManager::GetConcurrencyLimit

IDXTaskManager Interface

Retrieves the number of threads allowed to execute on a single processor at a given time.

Syntax

HRESULT GetConcurrencyLimit(
    ULONG *pulNumThreads
);

Parameters

pulNumThreads
[out] Pointer to the number of threads that can concurrently execute.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

See Also

IDXTaskManager::SetConcurrencyLimit

IDXTaskManager::GetThreadPoolSize

IDXTaskManager Interface

Retrieves the number of threads in the thread pool.

Syntax

HRESULT GetThreadPoolSize(
    ULONG *pulNumThreads
);

Parameters

pulNumThreads
[out] Pointer to the current thread pool size.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

See Also

IDXTaskManager::SetThreadPoolSize

IDXTaskManager::QueryNumProcessors

IDXTaskManager Interface

Retrieves the number of processors installed in the system.

Syntax

HRESULT QueryNumProcessors(
    ULONG *pulNumProc
);

Parameters

pulNumProc
[out] Pointer to the number of processors.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

IDXTaskManager::ScheduleTasks

IDXTaskManager Interface

Defines a set of tasks to execute.

Syntax

HRESULT ScheduleTasks(
    DXTMTASKINFO TaskInfo[],
    HANDLE Events[],
    DWORD TaskIDs[],
    ULONG ulNumTasks,
    ULONG ulWaitPeriod
);

Parameters

TaskInfo[]
[in] Array of one or more DXTMTASKINFO structures that define the task to be performed.

Events[]
[in] Optional array of event-object handles associated with each of the scheduled tasks.

TaskIDs[]
[out] Optional array used to receive the ID of each scheduled task.

ulNumTasks
[in] Number of tasks to be scheduled. This also defines the size of the arrays associated with the Events and TaskIDs parameters.

ulWaitPeriod
[in] Number of milliseconds to wait for each of the scheduled tasks to complete.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

This method adds a set of tasks to a FIFO queue for asynchronous execution. All tasks are queued using the calling thread. If the calling thread is supposed to wait and has finished queuing the tasks, it will start to execute tasks on the queue until the queue is empty. This reduces the amount of necessary context switches.
As each task is scheduled, the associated event, as specified by the Events parameter, is reset. As each task completes, the associated event is signaled.
If a nonzero value is supplied for the ulWaitPeriod parameter, the Events array is required and must have a valid event-object handle in each entry. A value of INFINITE can be used.
Each assigned task can use an Asynchronous Procedure Call (APC) or an event, but specifying both in the DXTMTASKINFO structure will result in the function returning E_INVALIDARG once it attempts to execute that task.

See Also

IDXTaskManager::TerminateTasks

IDXTaskManager::SetConcurrencyLimit

IDXTaskManager Interface

Defines the number of threads that can execute from a thread pool at a given time.

Syntax

HRESULT SetConcurrencyLimit(
	ULONG ulNumThreads
);

Parameters

ulNumThreads
[in] Number of threads from the thread pool that can concurrently execute. If zero, the number of threads will be set to the number of processors in the system.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

The ulNumThreads parameter is ignored on Windows 95 and 98. It is only a suggestion for Windows NT, where it is possible to temporarily exceed the concurrency limit. See the documentation for the IOCompletionPort interface in the MSDN Library's Knowledge Base for details.

See Also

IDXTaskManager::GetConcurrencyLimit

IDXTaskManager::SetThreadPoolSize

IDXTaskManager Interface

Specifies the number of threads that should be created and made available to execute tasks.

Syntax

HRESULT SetThreadPoolSize(
	ULONG ulNumThreads
);

Parameters

ulNumThreads
[in] Number of threads to make available in the thread pool.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

This method is used to define how many threads can be used to process tasks. If set to zero, the thread scheduling the work executes it.

See Also

IDXTaskManager::GetThreadPoolSize

IDXTaskManager::TerminateRequest

IDXTaskManager Interface

Terminates a task based on its request ID value that was used when it was scheduled.

Syntax

HRESULT TerminateRequest(
	REFIID RequestID,
	ULONG ulTimeOut
);

Parameters

RequestID
[in] ID that was used to schedule the tasks.

ulTimeOut
[in] Time, in milliseconds, to wait before terminating the specified task. If this parameter is zero, the task is terminated immediately.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

If the specified tasks are not running, they are removed from the queue. If they are running, they are signaled to stop.

See Also

DXTMTASKINFO, IDXTaskManager::ScheduleTasks

IDXTaskManager::TerminateTasks

IDXTaskManager Interface

Terminates a set of tasks previously scheduled by the task manager.

Syntax

HRESULT TerminateTasks(
    DWORD TaskIDs[],
    ULONG ulCount,
    ULONG ulTimeOut
);

Parameters

TaskIDs[]
[in] Array of IDs that specifies which tasks to terminate.

ulCount
[in] Number of tasks to terminate.

ulTimeOut
[in] Time, in milliseconds, to wait before terminating the specified tasks. If this parameter is zero, the tasks are terminated immediately.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

If the specified tasks are not running, they are removed from the queue. If they are running, they are signaled to stop.

See Also

DXTMTASKINFO, IDXTaskManager::ScheduleTasks

GetConcurrencyLimit	Retrieves the number of threads allowed to execute on a single processor at a given time.
GetThreadPoolSize	Retrieves the number of threads in the thread pool.
QueryNumProcessors	Retrieves the number of processors installed in the system.
ScheduleTasks	Defines a set of tasks to execute.
SetConcurrencyLimit	Defines the number of threads that can execute from a thread pool at a given time.
SetThreadPoolSize	Specifies the number of threads that should be created and made available to execute tasks.
TerminateRequest	Terminates a task based on its request ID value that was used when it was scheduled.
TerminateTasks	Terminates a set of tasks previously scheduled by the task manager.