ALib C++ Library
Library Version: 2510 R0
Documentation generated by doxygen
Loading...
Searching...
No Matches
jobs.inl
Go to the documentation of this file.
1//==================================================================================================
2/// \file
3/// This header-file is part of module \alib_threadmodel of the \aliblong.
4///
5/// \emoji :copyright: 2013-2025 A-Worx GmbH, Germany.
6/// Published under \ref mainpage_license "Boost Software License".
7//==================================================================================================
8ALIB_EXPORT namespace alib { namespace threadmodel
9{
10class DedicatedWorker;
11class ThreadPool;
12class DWManager;
13
14
15
16//==============================================================================================
17/// \attention This class belongs to module \alib_threadmodel, which is not in a stable and
18/// consistent state, yet.
19/// Also this type is considered experimental.
20///
21/// Defines jobs which are scheduled with instances of types \alib{threadmodel;ThreadPool} and
22/// \alib{threadmodel;DedicatedWorker}.<br>
23///
24/// The type is virtual and designed to be the base type for custom <em>"jobs"</em>.
25/// It holds a job-ID of type <c>std::type_info</c> which is used to identify the job type with
26/// processing.
27/// This ID usually represents - but does not need to! - the derived type.
28/// By including the ID into the job, one derived job-type object can be used with different
29/// job definitions.
30/// For example, built-in derived type \alib{threadmodel;JPromise} may be used as the "shared data"
31/// between the sender and the processing thread.
32/// The constructor of \b %JPromise accepts a type ID to store.
33///
34/// This explains that class Job has two main aspects:
35/// - Provide information to a worker thread about what is to be done.
36/// - Provide shared data between the sender and the worker.
37///
38/// Instances of this class are always \alib{monomem;TPoolAllocator;pool-allocated}.
39/// Allocation, construction, destruction and deletion are always under the control of either
40/// type \alib{threadmodel;ThreadPool} or \alib{threadmodel;DedicatedWorker}.
41/// Pool allocation requires passing the object size with deletion
42/// (all details on this topic is \ref alib_contmono_poolallocator_allocinfo "found here").
43/// For this, derived types that add new field members have to override method #SizeOf in a way
44/// described with the documentation of that virtual method, to return the correct size of the
45/// derived type.
46///
47/// Virtual method #Do has to be overridden in case a job is to be scheduled with class
48/// \alib{threadmodel;ThreadPool}.
49/// In case a derived type is (exclusively) used with type \alib{threadmodel;DedicatedWorker},
50/// it is up to the user of this module whether method #Do is implemented or not.
51/// If not, then a custom type derived from \b DedicatedWorker has to override method
52/// \alib{threadmodel::DedicatedWorker;process} and handle the job type there.
53///
54/// @see The Programmer's Manual of this module \alib_threadmodel for detailed information.
55//==============================================================================================
56struct Job
57{
58 /// The identifier of the job. Any custom type can be given. Jobs with complex
59 /// shared data types, which are used only for this specific job, usually use the
60 /// shared data type itself here.
61 const std::type_info& ID;
62
63 /// Protected constructor.
64 /// @param id Assigned to #ID.
65 Job( const std::type_info& id )
66 : ID (id) {}
67
68 /// Protected destructor.
69 virtual ~Job() = default;
70
71 /// This method is called by the worker thread in the case this job was scheduled
72 /// for deferred deletion using \alib{threadmodel;ThreadPool::DeleteJobDeferred}
73 /// or \alib{threadmodel;DedicatedWorker::DeleteJobDeferred}.
74 /// The method is intended to prepare the deletion of this job without further actions
75 /// that the sender of a job otherwise would perform.
76 ///
77 /// Overriding this method must be considered well. It is up to the contract between
78 /// the caller and the implementation of a custom worker, how to handle this situation.
79 ///
80 /// As a sample, within the implementation of this module, it is used with class
81 /// \alib{threadmodel;JPromise} to disable the warnings of deleting an unfulfilled and
82 /// un-awaited promise in debug-compilations.
83 ///
84 /// @note This method is called by the worker thread, so it is not allowed to be called
85 /// by any other methods of the worker or caller
86 virtual void PrepareDeferredDeletion() {}
87
88 /// Virtual method that returns the size of the type.<br>
89 /// Derived types that add fields or use multi-inheritance, have to override this virtual
90 /// function like done in this foundational version, but providing the custom type:
91 /// virtual size_t SizeOf() override
92 /// {
93 /// return sizeof(MyJobType);
94 /// }
95 ///
96 /// @return The sizeof this type. Derived types have to return their size.
97 virtual size_t SizeOf() { return sizeof(Job); }
98
99 /// Tests if this job's type ID equals the explicitly provided (non-deducible) template
100 /// type \p{TOther}.
101 /// @return \c true, if this instance represents job \p{TOther}, \c false otherwise.
102 template<typename TOther>
103 bool Is() { return ID == typeid(TOther); }
104
105 /// Tests if this instance is not initialized.
106 /// @return \c true, if this instance represents non-job-type <c>void</c>, and
107 /// \c false otherwise.
108 template<typename TOther>
109 bool IsNull() { return ID == typeid(void); }
110
111 /// Returns the shared data dynamically cast to provided (non-deducible) template type
112 /// \p{TJob}.<br>
113 /// With debug-compilations it is asserted that the requested job type \p{TJob} matches
114 /// to what it really is.
115 ///
116 /// @tparam TJob The true type <c>this</c> points to.
117 /// @return A reference to the shared data stored with this job.
118 template<typename TJob>
119 TJob& Cast()
120 {
121 ALIB_ASSERT_ERROR( typeid(TJob) == ID, "MGTHR",
122 "Bad job casting.\n"
123 " Job type: <{}>\n"
124 " Requested type: <{}>", &ID, &typeid(TJob) )
125
126 auto* result= dynamic_cast<TJob*>(this);
127
128 ALIB_ASSERT_ERROR( result != nullptr, "MGTHR",
129 "Job casting failed.\n"
130 " Job type: <{}>\n"
131 " Requested type: <{}>", &ID, &typeid(TJob) )
132 return *result;
133 }
134
135 /// Virtual function that may be overridden to execute the job when the job is executed by an
136 /// \alib{threadmodel;DedicatedWorker}.
137 /// In case it is executed by a \alib{threadmodel;ThreadPool} it has to be overridden.
138 ///
139 /// @return This default implementation returns \c false, which indicates that it is not
140 /// implemented.
141 /// Implementations need to return \c true.
142 virtual bool Do() { return false; }
143
144}; // struct Job
145
146/// A simple encapsulated promise.
147struct JPromise : public Job
148 , public Promise
149{
150 /// Constructor.
151 /// @param id The type-info of the derived type. Passed to parent class \b %Job.
152 JPromise(const std::type_info& id ) : Job(id) {}
153
154 /// Virtual destructor.
155 virtual ~JPromise() override= default;
156
157 /// Overrides the parent function as necessary.
158 /// @return The sizeof this derived type.
159 virtual size_t SizeOf() override { return sizeof(JPromise); }
160
161 #if ALIB_DEBUG
162 /// Overrides the parent function only with debug-compilations.
163 /// Avoids warnings about destroying unused promise
165 #endif
166};
167
168
169/// Possible priorities of jobs assigned to an \alib{threadmodel;DedicatedWorker}.
170enum class Priority
171{
172 Lowest = 0, ///< As the name indicates.
173 DeferredDeletion = 500, ///< As the name indicates.
174 Low = 1000, ///< As the name indicates.
175 Standard = 2000, ///< As the name indicates.
176 High = 3000, ///< As the name indicates.
177 Highest = 4000, ///< As the name indicates.
178};
179
180} // namespace alib[::threadmodel]
181
182/// Type alias in namespace \b alib.
184
185/// Type alias in namespace \b alib.
187
188} // namespace [alib]
189
190
191
void DbgOmitDestructionWarning()
Definition promise.inl:113
Promise()
Default constructor. Sets the state to State::Unfulfilled.
Definition promise.inl:91
#define ALIB_EXPORT
Definition alib.inl:488
#define ALIB_ASSERT_ERROR(cond, domain,...)
Definition alib.inl:1049
Priority
Possible priorities of jobs assigned to an DedicatedWorker.
Definition jobs.inl:171
@ DeferredDeletion
As the name indicates.
Definition jobs.inl:173
@ Low
As the name indicates.
Definition jobs.inl:174
@ Highest
As the name indicates.
Definition jobs.inl:177
@ High
As the name indicates.
Definition jobs.inl:176
@ Lowest
As the name indicates.
Definition jobs.inl:172
@ Standard
As the name indicates.
Definition jobs.inl:175
threadmodel::JPromise JPromise
Type alias in namespace alib.
Definition jobs.inl:186
threadmodel::Job Job
Type alias in namespace alib.
Definition jobs.inl:183
A simple encapsulated promise.
Definition jobs.inl:149
virtual ~JPromise() override=default
Virtual destructor.
virtual size_t SizeOf() override
Definition jobs.inl:159
virtual void PrepareDeferredDeletion() override
Definition jobs.inl:164
JPromise(const std::type_info &id)
Definition jobs.inl:152
virtual void PrepareDeferredDeletion()
Definition jobs.inl:86
virtual size_t SizeOf()
Definition jobs.inl:97
const std::type_info & ID
Definition jobs.inl:61
Job(const std::type_info &id)
Definition jobs.inl:65
virtual ~Job()=default
Protected destructor.
virtual bool Do()
Definition jobs.inl:142