Embedded Multicore Building Blocks V1.0.0
Public Types | Public Member Functions | Static Public Member Functions | List of all members
embb::mtapi::Node Class Reference

A singleton representing the MTAPI runtime. More...

#include <node.h>

Public Types

typedef embb::base::Function< void, TaskContext & > SMPFunction
 Function type for simple SMP interface. More...
 

Public Member Functions

 ~Node ()
 Destroys the runtime singleton. More...
 
mtapi_uint_t GetCoreCount () const
 Returns the number of available cores. More...
 
mtapi_uint_t GetWorkerThreadCount () const
 Returns the number of worker threads. More...
 
mtapi_uint_t GetQueueCount () const
 Returns the number of available queues. More...
 
mtapi_uint_t GetGroupCount () const
 Returns the number of available groups. More...
 
mtapi_uint_t GetTaskLimit () const
 Returns the number of available tasks. More...
 
Task Start (SMPFunction const &func)
 Starts a new Task. More...
 
Task Start (SMPFunction const &func, ExecutionPolicy const &policy)
 Starts a new Task with a given affinity and priority. More...
 
template<typename ARGS , typename RES >
Task Start (mtapi_task_id_t task_id, Job const &job, const ARGS *arguments, RES *results, TaskAttributes const &attributes)
 Starts a new Task. More...
 
template<typename ARGS , typename RES >
Task Start (mtapi_task_id_t task_id, Job const &job, const ARGS *arguments, RES *results)
 Starts a new Task. More...
 
template<typename ARGS , typename RES >
Task Start (Job const &job, const ARGS *arguments, RES *results, TaskAttributes const &attributes)
 Starts a new Task. More...
 
template<typename ARGS , typename RES >
Task Start (Job const &job, const ARGS *arguments, RES *results)
 Starts a new Task. More...
 
Job GetJob (mtapi_job_id_t job_id)
 Retrieves a handle to the Job identified by job_id within the domain of the local Node. More...
 
Job GetJob (mtapi_job_id_t job_id, mtapi_domain_t domain_id)
 Retrieves a handle to the Job identified by job_id and domain_id. More...
 
Action CreateAction (mtapi_job_id_t job_id, mtapi_action_function_t func, const void *node_local_data, mtapi_size_t node_local_data_size, ActionAttributes const &attributes)
 Constructs an Action. More...
 
Action CreateAction (mtapi_job_id_t job_id, mtapi_action_function_t func, const void *node_local_data, mtapi_size_t node_local_data_size)
 Constructs an Action. More...
 
Action CreateAction (mtapi_job_id_t job_id, mtapi_action_function_t func, ActionAttributes const &attributes)
 Constructs an Action. More...
 
Action CreateAction (mtapi_job_id_t job_id, mtapi_action_function_t func)
 Constructs an Action. More...
 
Group CreateGroup ()
 Constructs a Group object with default attributes. More...
 
Group CreateGroup (mtapi_group_id_t id)
 Constructs a Group object with default attributes and the given ID. More...
 
Group CreateGroup (GroupAttributes const &group_attr)
 Constructs a Group object using the given Attributes. More...
 
Group CreateGroup (mtapi_group_id_t id, GroupAttributes const &group_attr)
 Constructs a Group object with given attributes and ID. More...
 
Queue CreateQueue (Job &job)
 Constructs a Queue with the given Job and default attributes. More...
 
Queue CreateQueue (Job const &job, QueueAttributes const &attr)
 Constructs a Queue with the given Job and QueueAttributes. More...
 
Task Start (mtapi_task_id_t task_id, mtapi_job_hndl_t job, const void *arguments, mtapi_size_t arguments_size, void *results, mtapi_size_t results_size, mtapi_task_attributes_t const *attributes)
 Starts a new Task. More...
 
void YieldToScheduler ()
 This function yields execution to the MTAPI scheduler for at most one task. More...
 

Static Public Member Functions

static void Initialize (mtapi_domain_t domain_id, mtapi_node_t node_id)
 Initializes the runtime singleton using default values: More...
 
static void Initialize (mtapi_domain_t domain_id, mtapi_node_t node_id, NodeAttributes const &attributes)
 Initializes the runtime singleton. More...
 
static bool IsInitialized ()
 Checks if runtime is initialized. More...
 
static NodeGetInstance ()
 Gets the instance of the runtime system. More...
 
static void Finalize ()
 Shuts the runtime system down. More...
 

Detailed Description

A singleton representing the MTAPI runtime.

Member Typedef Documentation

Function type for simple SMP interface.

Constructor & Destructor Documentation

embb::mtapi::Node::~Node ( )

Destroys the runtime singleton.

Concurrency
Not thread-safe

Member Function Documentation

static void embb::mtapi::Node::Initialize ( mtapi_domain_t  domain_id,
mtapi_node_t  node_id 
)
static

Initializes the runtime singleton using default values:

  • all available cores will be used
  • maximum number of tasks is 1024
  • maximum number of groups is 128
  • maximum number of queues is 16
  • maximum queue capacity is 1024
  • maximum number of priorities is 4.
Concurrency
Not thread-safe
Exceptions
ErrorExceptionif the singleton was already initialized or the Node could not be initialized.
Dynamic memory allocation
Allocates about 200kb of memory.
Parameters
[in]domain_idThe domain id to use
[in]node_idThe node id to use
static void embb::mtapi::Node::Initialize ( mtapi_domain_t  domain_id,
mtapi_node_t  node_id,
NodeAttributes const &  attributes 
)
static

Initializes the runtime singleton.

Concurrency
Not thread-safe
Exceptions
ErrorExceptionif the singleton was already initialized or the Node could not be initialized.
Dynamic memory allocation
Allocates some memory depending on the values given.
Parameters
[in]domain_idThe domain id to use
[in]node_idThe node id to use
[in]attributesAttributes to use
static bool embb::mtapi::Node::IsInitialized ( )
static

Checks if runtime is initialized.

Returns
true if the Node singleton is already initialized, false otherwise
Concurrency
Thread-safe and wait-free
static Node& embb::mtapi::Node::GetInstance ( )
static

Gets the instance of the runtime system.

Returns
Reference to the Node singleton
Concurrency
Thread-safe
static void embb::mtapi::Node::Finalize ( )
static

Shuts the runtime system down.

Exceptions
ErrorExceptionif the singleton is not initialized.
Concurrency
Not thread-safe
mtapi_uint_t embb::mtapi::Node::GetCoreCount ( ) const

Returns the number of available cores.

Returns
The number of available cores
Concurrency
Thread-safe and wait-free
mtapi_uint_t embb::mtapi::Node::GetWorkerThreadCount ( ) const

Returns the number of worker threads.

Returns
The number of worker threads.
Concurrency
Thread-safe and wait-free
mtapi_uint_t embb::mtapi::Node::GetQueueCount ( ) const

Returns the number of available queues.

Returns
The number of available queues
Concurrency
Thread-safe and wait-free
mtapi_uint_t embb::mtapi::Node::GetGroupCount ( ) const

Returns the number of available groups.

Returns
The number of available groups
Concurrency
Thread-safe and wait-free
mtapi_uint_t embb::mtapi::Node::GetTaskLimit ( ) const

Returns the number of available tasks.

Returns
The number of available tasks
Concurrency
Thread-safe and wait-free
Task embb::mtapi::Node::Start ( SMPFunction const &  func)

Starts a new Task.

Returns
The handle to the started Task.
Concurrency
Thread-safe
Parameters
funcFunction to use for the task.
Task embb::mtapi::Node::Start ( SMPFunction const &  func,
ExecutionPolicy const &  policy 
)

Starts a new Task with a given affinity and priority.

Returns
The handle to the started Task.
Concurrency
Thread-safe
Parameters
funcFunction to use for the task.
policyAffinity and priority of the task.
template<typename ARGS , typename RES >
Task embb::mtapi::Node::Start ( mtapi_task_id_t  task_id,
Job const &  job,
const ARGS *  arguments,
RES *  results,
TaskAttributes const &  attributes 
)

Starts a new Task.

Returns
The handle to the started Task.
Concurrency
Thread-safe
Parameters
task_idA user defined ID of the Task.
jobThe Job to execute.
argumentsPointer to the arguments.
resultsPointer to the results.
attributesAttributes of the Task
template<typename ARGS , typename RES >
Task embb::mtapi::Node::Start ( mtapi_task_id_t  task_id,
Job const &  job,
const ARGS *  arguments,
RES *  results 
)

Starts a new Task.

Returns
The handle to the started Task.
Concurrency
Thread-safe
Parameters
task_idA user defined ID of the Task.
jobThe Job to execute.
argumentsPointer to the arguments.
resultsPointer to the results.
template<typename ARGS , typename RES >
Task embb::mtapi::Node::Start ( Job const &  job,
const ARGS *  arguments,
RES *  results,
TaskAttributes const &  attributes 
)

Starts a new Task.

Returns
The handle to the started Task.
Concurrency
Thread-safe
Parameters
jobThe Job to execute.
argumentsPointer to the arguments.
resultsPointer to the results.
attributesAttributes of the Task
template<typename ARGS , typename RES >
Task embb::mtapi::Node::Start ( Job const &  job,
const ARGS *  arguments,
RES *  results 
)

Starts a new Task.

Returns
The handle to the started Task.
Concurrency
Thread-safe
Parameters
jobThe Job to execute.
argumentsPointer to the arguments.
resultsPointer to the results.
Job embb::mtapi::Node::GetJob ( mtapi_job_id_t  job_id)

Retrieves a handle to the Job identified by job_id within the domain of the local Node.

Returns
The handle to the requested Job.
Concurrency
Thread-safe and wait-free
Parameters
[in]job_idThe id of the job
Job embb::mtapi::Node::GetJob ( mtapi_job_id_t  job_id,
mtapi_domain_t  domain_id 
)

Retrieves a handle to the Job identified by job_id and domain_id.

Returns
The handle to the requested Job.
Concurrency
Thread-safe and wait-free
Parameters
[in]job_idThe id of the job
[in]domain_idThe domain id to use
Action embb::mtapi::Node::CreateAction ( mtapi_job_id_t  job_id,
mtapi_action_function_t  func,
const void *  node_local_data,
mtapi_size_t  node_local_data_size,
ActionAttributes const &  attributes 
)

Constructs an Action.

Returns
The handle to the new Action.
Concurrency
Thread-safe and lock-free
Parameters
job_idJob ID the Action belongs to
funcThe action function
node_local_dataNode local data available to all Tasks using this Action
node_local_data_sizeSize of node local data
attributesAttributes of the Action
Action embb::mtapi::Node::CreateAction ( mtapi_job_id_t  job_id,
mtapi_action_function_t  func,
const void *  node_local_data,
mtapi_size_t  node_local_data_size 
)

Constructs an Action.

Returns
The handle to the new Action.
Concurrency
Thread-safe and lock-free
Parameters
job_idJob ID the Action belongs to
funcThe action function
node_local_dataNode local data available to all Tasks using this Action
node_local_data_sizeSize of node local data
Action embb::mtapi::Node::CreateAction ( mtapi_job_id_t  job_id,
mtapi_action_function_t  func,
ActionAttributes const &  attributes 
)

Constructs an Action.

Returns
The handle to the new Action.
Concurrency
Thread-safe and lock-free
Parameters
job_idJob ID the Action belongs to
funcThe action function
attributesAttributes of the Action
Action embb::mtapi::Node::CreateAction ( mtapi_job_id_t  job_id,
mtapi_action_function_t  func 
)

Constructs an Action.

Returns
The handle to the new Action.
Concurrency
Thread-safe and lock-free
Parameters
job_idJob ID the Action belongs to
funcThe action function
Group embb::mtapi::Node::CreateGroup ( )

Constructs a Group object with default attributes.

Returns
The handle to the new Group.
Concurrency
Thread-safe and lock-free
Group embb::mtapi::Node::CreateGroup ( mtapi_group_id_t  id)

Constructs a Group object with default attributes and the given ID.

Returns
The handle to the new Group.
Concurrency
Thread-safe and lock-free
Parameters
idA user defined ID of the Group.
Group embb::mtapi::Node::CreateGroup ( GroupAttributes const &  group_attr)

Constructs a Group object using the given Attributes.

Returns
The handle to the new Group.
Concurrency
Thread-safe and lock-free
Parameters
group_attrThe GroupAttributes to use.
Group embb::mtapi::Node::CreateGroup ( mtapi_group_id_t  id,
GroupAttributes const &  group_attr 
)

Constructs a Group object with given attributes and ID.

Returns
The handle to the new Group.
Concurrency
Thread-safe and lock-free
Parameters
idA user defined ID of the Group.
group_attrThe GroupAttributes to use.
Queue embb::mtapi::Node::CreateQueue ( Job job)

Constructs a Queue with the given Job and default attributes.

Returns
The handle to the new Queue.
Concurrency
Thread-safe and lock-free
Parameters
jobThe Job to use for the Queue.
Queue embb::mtapi::Node::CreateQueue ( Job const &  job,
QueueAttributes const &  attr 
)

Constructs a Queue with the given Job and QueueAttributes.

Returns
The handle to the new Queue.
Concurrency
Thread-safe and lock-free
Parameters
jobThe Job to use for the Queue.
attrThe attributes to use.
Task embb::mtapi::Node::Start ( mtapi_task_id_t  task_id,
mtapi_job_hndl_t  job,
const void *  arguments,
mtapi_size_t  arguments_size,
void *  results,
mtapi_size_t  results_size,
mtapi_task_attributes_t const *  attributes 
)

Starts a new Task.

Returns
The handle to the started Task.
Concurrency
Thread-safe
Parameters
task_idA user defined ID of the Task.
jobThe Job to execute.
argumentsPointer to the arguments buffer
arguments_sizeSize of the arguments buffer
resultsPointer to the result buffer
results_sizeSize of the result buffer
attributesAttributes to use for the task
void embb::mtapi::Node::YieldToScheduler ( )

This function yields execution to the MTAPI scheduler for at most one task.

Concurrency
Thread-safe