Thread Management API

Implementation of platform-agnostic CPU threads. More...

Data Structures
struct	AtParallelJobs
	Work scheduler structure that can run jobs in parallel. More...

Macros
#define	AI_MAX_THREADS   1024
	maximum number of threads

Typedefs
typedef void(*	AtParallelForFunc) (size_t array_index, void *data, void *payload)
typedef void *	AtParallelJobsID
typedef void(*	AtParallelJobsFunc) (void *payload)

Functions
AI_API void *	AiThreadCreate (unsigned int(*fn)(void *), void *data, int priority)
	Creates a thread and returns a handler for the thread. More...
AI_API void	AiThreadClose (void *thread)
	Closes thread handle, to avoid resource leaks. More...
AI_API void	AiThreadWait (void *thread)
	Wait for a thread to finish. More...
AI_API AI_CONST void *	AiThreadSelf ()
	Returns a handle for the current (calling) thread. More...
AI_API void	AiParallelFor (void *array_of_data, size_t data_size, size_t num_data, void *payload, AtParallelForFunc job)
	Operate on an array of data in parallel. More...
AI_API AtParallelJobsID	AiParallelJobsCreateID ()
	Create a work scheduler, for running jobs in parallel. More...
AI_API void	AiParallelJobsDestroy (AtParallelJobsID jobsID)
	Destroy the parallel work scheduler. More...
AI_API void	AiParallelJobsDispatch (AtParallelJobsID jobsID, void *payload, AtParallelJobsFunc job)
	Run a new job that will be executed in a separate thread. More...
AI_API void	AiParallelJobsWait (AtParallelJobsID jobsID)
	Wait until all jobs of a given work scheduler have ended. More...
void	AtParallelJobs::add (void *payload, AtParallelJobsFunc job)
void	AtParallelJobs::wait ()

Variables
AtParallelJobsID	AtParallelJobs::m_jobs

Thread Priorities
#define	AI_PRIORITY_LOWEST   0x00
	even lower priority than AI_PRIORITY_LOW
#define	AI_PRIORITY_LOW   0x01
	low thread priority
#define	AI_PRIORITY_NORMAL   0x02
	normal thread priority
#define	AI_PRIORITY_HIGH   0x03
	high thread priority

Detailed Description

Implementation of platform-agnostic CPU threads.

Function Documentation

AiThreadCreate()

AI_API void * AiThreadCreate	(	unsigned int(*)(void *)	fn,
		void *	data,
		int	priority
	)

Creates a thread and returns a handler for the thread.

After the thread is finished, a pairing call to AiThreadClose() is needed to avoid resource leaks.

The thread priority is valid only for Windows. For example, a render manager that takes advantage of unused background CPU cycles in an artist's workstation would probably want to use lowest priority threads so that other applications can run smoothly.

Parameters

fn	pointer to the function the new thread will execute
data	data pointer for new thread
priority	priority of thread, e.g. AI_PRIORITY_LOW, etc; has no effect on Linux and OS X

Returns

thread handle of the newly created thread

See also

AiThreadClose, AiThreadWait, AiThreadSelf

AiThreadClose()

AI_API void AiThreadClose

(

void *

thread

)

Closes thread handle, to avoid resource leaks.

The thread is effectively destroyed so the handle can't be used anymore.

Parameters

thread

thread handle

See also

AiThreadCreate

AiThreadWait()

AI_API void AiThreadWait

(

void *

thread

)

Wait for a thread to finish.

This function will not return until the thread finishes executing its user-supplied function. The thread handle must point to an existing thread that has not been destroyed with AiThreadClose(), otherwise the behaviour is undefined.

Parameters

thread

thread handle

See also

AiThreadCreate, AiThreadClose

AiThreadSelf()

AI_API void * AiThreadSelf

(

)

Returns a handle for the current (calling) thread.

Returns

thread handle

See also

AiThreadCreate

AiParallelFor()

AI_API void AiParallelFor	(	void *	array_of_data,
		size_t	data_size,
		size_t	num_data,
		void *	payload,
		AtParallelForFunc	job
	)

Operate on an array of data in parallel.

This has less overhead than AiParallelJobs(), and should be the preferred method when a parallelized job operates on an array of data. Effectively, this is a parallel_for over array_of_data, iterating from the first element of the array to the num_data element, where job() is executed on each of the elements. There is no guarantee on the order of execution over the array elements.

Parameters

array_of_data	pointer to data array
data_size	size of each element of the array
num_data	number of elements in the array
payload	common payload to pass to each job
job	function pointer

For example:

// simple example that in-place squares all the elements in an array
// and writes into a new array the log of the squared values
void per_element_function(size_t array_index, void* data, void* payload)
{
   float& value = *static_cast<float*>(data);
   value        = value * value;
   static_cast<float*>(payload)[array_index] = std::log(value);
}
 
std::array<float, 7> values = {1, 2, 3, 5, 8, 13, 21};
float log_squared_output[7];
AiParallelFor(values.data(), sizeof(values[0]), values.size(), log_squared_output, per_element_function);

AiParallelJobsCreateID()

AI_API AtParallelJobsID AiParallelJobsCreateID

(

)

Create a work scheduler, for running jobs in parallel.

Returns

Identifier for a new work scheduler

AiParallelJobsDestroy()

AI_API void AiParallelJobsDestroy

(

AtParallelJobsID

jobsID

)

Destroy the parallel work scheduler.

Parameters

jobsID

Identifier for a work scheduler to be deleted

AiParallelJobsDispatch()

AI_API void AiParallelJobsDispatch	(	AtParallelJobsID	jobsID,
		void *	payload,
		AtParallelJobsFunc	job
	)

Run a new job that will be executed in a separate thread.

This function is non-blocking.

Parameters

jobsID	Identifier for a work scheduler to be used
payload	Custom payload to be passed to the job
job	function pointer that will be invoked for this job

AiParallelJobsWait()

AI_API void AiParallelJobsWait

(

AtParallelJobsID

jobsID

)

Wait until all jobs of a given work scheduler have ended.

Parameters

jobsID

Identifier for a work scheduler. The function will only return when all its jobs have ended.