Job Struct Reference

Description:

Attention

This class belongs to module ALib ThreadModel, which is not in a stable and consistent state, yet. Also this type is considered experimental.

Defines jobs which are scheduled with instances of types ThreadPool and DedicatedWorker.

The type is virtual and designed to be the base type for custom "jobs". It holds a job-ID of type std::type_info which is used to identify the job type with processing. This ID usually represents - but does not need to! - the derived type. By including the ID into the job, one derived job-type object can be used with different job definitions. For example, built-in derived type JPromise may be used as the "shared data" between the sender and the processing thread. The constructor of JPromise accepts a type ID to store.

This explains that class Job has two main aspects:

• Provide information to a worker thread about what is to be done.
• Provide shared data between the sender and the worker.

Instances of this class are always pool-allocated. Allocation, construction, destruction and deletion are always under the control of either type ThreadPool or DedicatedWorker. Pool allocation requires passing the object size with deletion (all details on this topic is found here). For this, derived types that add new field members have to override method SizeOf in a way described with the documentation of that virtual method, to return the correct size of the derived type.

Virtual method Do has to be overridden in case a job is to be scheduled with class ThreadPool. In case a derived type is (exclusively) used with type DedicatedWorker, it is up to the user of this module whether method Do is implemented or not. If not, then a custom type derived from DedicatedWorker has to override method process and handle the job type there.

See also

The Programmer's Manual of this module ALib ThreadModel for detailed information.

Definition at line 71 of file jobs.hpp.

#include <jobs.hpp>

Inheritance diagram for Job:

Public Field Index:
const std::type_info &	ID

Public Method Index:
	Job (const std::type_info &id)
virtual	~Job ()=default
	Protected destructor.
template<typename TJob >
TJob &	Cast ()
virtual bool	Do ()
template<typename TOther >
bool	Is ()
template<typename TOther >
bool	IsNull ()
virtual void	PrepareDeferredDeletion ()
virtual size_t	SizeOf ()

Field Details:

ID

const std::type_info& ID

The identifier of the job. Any custom type can be given. Jobs with complex shared data types, which are used only for this specific job, usually use the shared data type itself here.

Definition at line 76 of file jobs.hpp.

Constructor(s) / Destructor Details:

Job()

Job ( const std::type_info & id )

inline

Protected constructor.

Parameters

id	Assigned to ID.

Definition at line 80 of file jobs.hpp.

Method Details:

Cast()

template<typename TJob >

TJob & Cast ( )

inline

Returns the shared data dynamically cast to provided (non-deducible) template type TJob.
With debug-compilations it is asserted that the requested job type TJob matches to what it really is.

Template Parameters

TJob	The true type this points to.

Returns

A reference to the shared data stored with this job.

Definition at line 134 of file jobs.hpp.

Do()

virtual bool Do ( )

inlinevirtual

Virtual function that may be overridden to execute the job when the job is executed by an DedicatedWorker. In case it is executed by a ThreadPool it has to be overridden.

Returns

This default implementation returns false, which indicates that it is not implemented. Implementations need to return true.

Definition at line 158 of file jobs.hpp.

Is()

template<typename TOther >

bool Is ( )

inline

Tests if this job's type ID equals the explicitly provided (non-deducible) template type TOther.

Returns

true, if this instance represents job TOther, false otherwise.

Definition at line 118 of file jobs.hpp.

IsNull()

template<typename TOther >

bool IsNull ( )

inline

Tests if this instance is not initialized.

Returns

true, if this instance represents non-job-type void, and false otherwise.

Definition at line 124 of file jobs.hpp.

PrepareDeferredDeletion()

virtual void PrepareDeferredDeletion ( )

inlinevirtual

This method is called by the worker thread in the case this job was scheduled for deferred deletion using ThreadPool::DeleteJobDeferred or DedicatedWorker::DeleteJobDeferred. The method is intended to prepare the deletion of this job without further actions that the sender of a job otherwise would perform.

Overriding this method must be considered well. It is up to the contract between the caller and the implementation of a custom worker, how to handle this situation.

As a sample, within the implementation of this module, it is used with class JPromise to disable the warnings of deleting an unfulfilled and un-awaited promise in debug-compilations.

Note

This method is called by the worker thread, so it is not allowed to be called by any other methods of the worker or caller

Reimplemented in JPromise.

Definition at line 101 of file jobs.hpp.

SizeOf()

virtual size_t SizeOf ( )

inlinevirtual

Virtual method that returns the size of the type.
Derived types that add fields or use multi-inheritance, have to override this virtual function like done in this foundational version, but providing the custom type: virtual size_t SizeOf() override { return sizeof(MyJobType); }

Returns

The sizeof this type. Derived types have to return their size.

Reimplemented in DedicatedWorker::JobDeleter, JPromise, and ThreadPool::JobSyncer.

Definition at line 112 of file jobs.hpp.

---

The documentation for this struct was generated from the following file:

• jobs.hpp