Task Interface

A task which may be repeated in parallel with different inputs.

A Task should represent an instance of the task to complete (e.g. a Metropolis-Hastings random walk).

A Task interface compliant type should provide the following methods.

typedef .. StatusReportType

The type storing information for a status report (task progress, message, additional info such as acceptance ratio etc.). This class must inherit from Tomographer::MultiProc::TaskStatusReport, such that at least fraction_done and msg are provided. (So that generic status reporter helpers such as Tomographer::Tools::SigHandlerTaskDispatcherStatusReporter can at least rely on this information.)

Task(InputType input, const TaskCData * pcdata, LoggerType & logger)

Task constructor: construct a Task instance which will solve the task for the given input. The input parameter is whatever TaskCData::getTaskInput() returned.

This method can log to the given logger (see Tomographer::Logger::LoggerBase). Note that the logger need NOT be the logger that may have been specified, e.g., to the task dispatcher: it could be, for example, an internal thread-safe wrapper to your original logger. To be sure, you should make this a template method with a parameter LoggerType.

void run(const TaskCData * pcdata, LoggerType & logger, TaskManagerIface * tmgriface)

This method actually runs the task.

This method can log to the given logger (see Tomographer::Logger::LoggerBase). Note that the logger need NOT be the logger that may have been specified, e.g., to the task dispatcher: it could be, for example, an internal thread-safe wrapper to your original logger. To be sure, you should make this a template method with parameters LoggerType and TaskManagerIface.

The code in run() should poll tmgriface->statusReportRequested() and provide a status report if requested to do so via tmgriface->statusReport(const TaskStatusReportType &). tmgriface is an object which complies to the TaskManagerIface Interface.

A Task interface compliant type must always also be compliant with the Resultable Interface, meaning that it must provide the following methods:

typedef .. ResultType

An alias for the type, e.g. a structure, which contains the result of the given task. See Task::getResult(). See the Resultable Interface.

ResultType getResult()

Return a custom type which holds the result for the given task. See the Resultable Interface.

ResultType stealResult()

Return a custom type which holds the result for the given task. The caller guarantees that no further calls to getResult() and stealResult() will occur. See the Resultable Interface.

Note on Status Reports:

Tasks must regularly check whether a status report has been requested as they run. This is done by regularly calling the function tmgriface->statusReportRequested() on the tmgriface object provided to TaskType::run(). This function call is meant to be very efficient (for example, it does not require a critical section in the OpenMP implementation), so this check can be done often. The function tmgriface->statusReportRequested() returns a bool indicating whether such a report was requested or not. If such a report was requested, then the thread should prepare its status report object (of type TaskStatusReportType), and call tmgriface->submitStatusReport(const TaskStatusReportType & obj).

The task should provide a member type named StatusReportType, which can be for example a simple typedef to Tomographer::MultiProc::TaskStatusReport, which specifies the type of its status reports.