alib::threadmodel::Job Struct Reference

Description:

Attention

This class belongs to the 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 in 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. It

• provides information to a worker thread about what is to be done.
• provides 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. 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. (All details on this topic are found here).

Virtual method Do has to be overridden in case a job is to be scheduled with the 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 the 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 54 of file jobs.inl.

Inheritance diagram for alib::threadmodel::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& alib::threadmodel::Job::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 59 of file jobs.inl.

Constructor(s) / Destructor Details:

Job()

alib::threadmodel::Job::Job ( const std::type_info & id )

inline

Protected constructor.

Parameters

id	Assigned to ID.

Definition at line 63 of file jobs.inl.

Method Details:

Cast()

template<typename TJob>

TJob & alib::threadmodel::Job::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 117 of file jobs.inl.

Do()

virtual bool alib::threadmodel::Job::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 139 of file jobs.inl.

Is()

template<typename TOther>

bool alib::threadmodel::Job::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 101 of file jobs.inl.

IsNull()

template<typename TOther>

bool alib::threadmodel::Job::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 107 of file jobs.inl.

PrepareDeferredDeletion()

virtual void alib::threadmodel::Job::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 alib::threadmodel::JPromise.

Definition at line 84 of file jobs.inl.

SizeOf()

virtual size_t alib::threadmodel::Job::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 alib::threadmodel::DedicatedWorker::JobDeleter, alib::threadmodel::JPromise, and alib::threadmodel::ThreadPool::JobSyncer.

Definition at line 95 of file jobs.inl.

Here is the call graph for this function:

---

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

• jobs.inl