1 //
2 // Copyright (c) 2008-2017 the Urho3D project.
3 //
4 // Permission is hereby granted, free of charge, to any person obtaining a copy
5 // of this software and associated documentation files (the "Software"), to deal
6 // in the Software without restriction, including without limitation the rights
7 // to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
8 // copies of the Software, and to permit persons to whom the Software is
9 // furnished to do so, subject to the following conditions:
10 //
11 // The above copyright notice and this permission notice shall be included in
12 // all copies or substantial portions of the Software.
13 //
14 // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15 // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16 // FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
17 // AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
18 // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
19 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
20 // THE SOFTWARE.
21 //
22
23 #pragma once
24
25 #include "../Container/List.h"
26 #include "../Core/Mutex.h"
27 #include "../Core/Object.h"
28
29 namespace Urho3D
30 {
31
32 /// Work item completed event.
URHO3D_EVENT(E_WORKITEMCOMPLETED,WorkItemCompleted)33 URHO3D_EVENT(E_WORKITEMCOMPLETED, WorkItemCompleted)
34 {
35 URHO3D_PARAM(P_ITEM, Item); // WorkItem ptr
36 }
37
38 class WorkerThread;
39
40 /// Work queue item.
41 struct WorkItem : public RefCounted
42 {
43 friend class WorkQueue;
44
45 public:
46 // Construct
WorkItemWorkItem47 WorkItem() :
48 priority_(0),
49 sendEvent_(false),
50 completed_(false),
51 pooled_(false)
52 {
53 }
54
55 /// Work function. Called with the work item and thread index (0 = main thread) as parameters.
56 void (* workFunction_)(const WorkItem*, unsigned);
57 /// Data start pointer.
58 void* start_;
59 /// Data end pointer.
60 void* end_;
61 /// Auxiliary data pointer.
62 void* aux_;
63 /// Priority. Higher value = will be completed first.
64 unsigned priority_;
65 /// Whether to send event on completion.
66 bool sendEvent_;
67 /// Completed flag.
68 volatile bool completed_;
69
70 private:
71 bool pooled_;
72 };
73
74 /// Work queue subsystem for multithreading.
75 class URHO3D_API WorkQueue : public Object
76 {
77 URHO3D_OBJECT(WorkQueue, Object);
78
79 friend class WorkerThread;
80
81 public:
82 /// Construct.
83 WorkQueue(Context* context);
84 /// Destruct.
85 ~WorkQueue();
86
87 /// Create worker threads. Can only be called once.
88 void CreateThreads(unsigned numThreads);
89 /// Get pointer to an usable WorkItem from the item pool. Allocate one if no more free items.
90 SharedPtr<WorkItem> GetFreeItem();
91 /// Add a work item and resume worker threads.
92 void AddWorkItem(SharedPtr<WorkItem> item);
93 /// Remove a work item before it has started executing. Return true if successfully removed.
94 bool RemoveWorkItem(SharedPtr<WorkItem> item);
95 /// Remove a number of work items before they have started executing. Return the number of items successfully removed.
96 unsigned RemoveWorkItems(const Vector<SharedPtr<WorkItem> >& items);
97 /// Pause worker threads.
98 void Pause();
99 /// Resume worker threads.
100 void Resume();
101 /// Finish all queued work which has at least the specified priority. Main thread will also execute priority work. Pause worker threads if no more work remains.
102 void Complete(unsigned priority);
103
104 /// Set the pool telerance before it starts deleting pool items.
SetTolerance(int tolerance)105 void SetTolerance(int tolerance) { tolerance_ = tolerance; }
106
107 /// Set how many milliseconds maximum per frame to spend on low-priority work, when there are no worker threads.
SetNonThreadedWorkMs(int ms)108 void SetNonThreadedWorkMs(int ms) { maxNonThreadedWorkMs_ = Max(ms, 1); }
109
110 /// Return number of worker threads.
GetNumThreads()111 unsigned GetNumThreads() const { return threads_.Size(); }
112
113 /// Return whether all work with at least the specified priority is finished.
114 bool IsCompleted(unsigned priority) const;
115 /// Return whether the queue is currently completing work in the main thread.
IsCompleting()116 bool IsCompleting() const { return completing_; }
117
118 /// Return the pool tolerance.
GetTolerance()119 int GetTolerance() const { return tolerance_; }
120
121 /// Return how many milliseconds maximum to spend on non-threaded low-priority work.
GetNonThreadedWorkMs()122 int GetNonThreadedWorkMs() const { return maxNonThreadedWorkMs_; }
123
124 private:
125 /// Process work items until shut down. Called by the worker threads.
126 void ProcessItems(unsigned threadIndex);
127 /// Purge completed work items which have at least the specified priority, and send completion events as necessary.
128 void PurgeCompleted(unsigned priority);
129 /// Purge the pool to reduce allocation where its unneeded.
130 void PurgePool();
131 /// Return a work item to the pool.
132 void ReturnToPool(SharedPtr<WorkItem>& item);
133 /// Handle frame start event. Purge completed work from the main thread queue, and perform work if no threads at all.
134 void HandleBeginFrame(StringHash eventType, VariantMap& eventData);
135
136 /// Worker threads.
137 Vector<SharedPtr<WorkerThread> > threads_;
138 /// Work item pool for reuse to cut down on allocation. The bool is a flag for item pooling and whether it is available or not.
139 List<SharedPtr<WorkItem> > poolItems_;
140 /// Work item collection. Accessed only by the main thread.
141 List<SharedPtr<WorkItem> > workItems_;
142 /// Work item prioritized queue for worker threads. Pointers are guaranteed to be valid (point to workItems.)
143 List<WorkItem*> queue_;
144 /// Worker queue mutex.
145 Mutex queueMutex_;
146 /// Shutting down flag.
147 volatile bool shutDown_;
148 /// Pausing flag. Indicates the worker threads should not contend for the queue mutex.
149 volatile bool pausing_;
150 /// Paused flag. Indicates the queue mutex being locked to prevent worker threads using up CPU time.
151 bool paused_;
152 /// Completing work in the main thread flag.
153 bool completing_;
154 /// Tolerance for the shared pool before it begins to deallocate.
155 int tolerance_;
156 /// Last size of the shared pool.
157 unsigned lastSize_;
158 /// Maximum milliseconds per frame to spend on low-priority work, when there are no worker threads.
159 int maxNonThreadedWorkMs_;
160 };
161
162 }
163