HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
singularTask.h
Go to the documentation of this file.
1 //
2 // Copyright 2016 Pixar
3 //
4 // Licensed under the terms set forth in the LICENSE.txt file available at
5 // https://openusd.org/license.
6 //
7 #ifndef PXR_BASE_WORK_SINGULAR_TASK_H
8 #define PXR_BASE_WORK_SINGULAR_TASK_H
9 
10 /// \file work/singularTask.h
11 
12 #include "pxr/pxr.h"
13 
14 #include <atomic>
15 #include <functional>
16 #include <type_traits>
17 
19 
20 class WorkDispatcher;
21 
22 /// \class WorkSingularTask
23 ///
24 /// A WorkSingularTask runs a task in a WorkDispatcher, but never concurrently
25 /// with itself. That is, the function provided to the WorkSingularTask runs
26 /// concurrently with other tasks in the WorkDispatcher, but never with another
27 /// invocation of itself.
28 ///
29 /// This is useful if there is single-threaded work to do that can be overlapped
30 /// with other parallel tasks in a dispatcher. For example, a
31 /// multiple-producer, single-consumer problem can be tackled this way. Run the
32 /// producer tasks as usual in a WorkDispatcher and create a WorkSingularTask
33 /// for the consumer. When a producer task has generated a result to consume,
34 /// it invokes Wake() on the consumer task. This ensures that the consumer runs
35 /// only when there are results to consume, and it lets the consumer operate
36 /// single-threaded. For example, the consumer could populate stl containers
37 /// without locking.
38 ///
40 {
41 public:
42 
43  WorkSingularTask(WorkSingularTask const &) = delete;
44  WorkSingularTask &operator=(WorkSingularTask const &) = delete;
45 
46 #ifdef doxygen
47 
48  /// Create a singular task to be run in \p dispatcher. Callers must ensure
49  /// that \p dispatcher lives at least as long as this WorkSingularTask.
50  ///
51  /// A singular task is one that will not run concurrently with itself. See
52  /// the WorkSingularTask doc for more details.
53  ///
54  /// After constructing a WorkSingularTask, call Wake() to ensure that the
55  /// task runs at least once.
56  template <class Callable, class A1, class A2, ... class AN>
57  WorkSingularTask(WorkDispatcher &dispatcher,
58  Callable &&c, A1 &&a1, A2 &&a2, ... AN &&aN);
59 
60 #else // doxygen
61 
62  template <class Callable, class... Args>
63  WorkSingularTask(WorkDispatcher &d, Callable &&c, Args&&... args)
64  : _waker(_MakeWaker(d, std::bind(std::forward<Callable>(c),
65  std::forward<Args>(args)...)))
66  , _count(0) {}
67 
68 #endif // doxygen
69 
70  /// Ensure that this task runs at least once after this call. The task is
71  /// not guaranteed to run as many times as Wake() is invoked, only that it
72  /// run at least once after a call to Wake().
73  inline void Wake() {
74  if (++_count == 1)
75  _waker(_count);
76  }
77 
78 private:
79  template <class Dispatcher, class Fn>
80  struct _Waker {
81  explicit _Waker(Dispatcher &d, Fn &&fn)
82  : _dispatcher(d), _fn(std::move(fn)) {}
83 
84  void operator()(std::atomic_size_t &count) const {
85  _dispatcher.Run(
86  [this, &count]() {
87  // We read the current refCount into oldCount, then we
88  // invoke the task function. Finally we try to CAS the
89  // refCount to zero. If we fail, it means some other
90  // clients have invoked Wake() in the meantime. In that
91  // case we go again to ensure the task can do whatever it
92  // was awakened to do. Once we successfully take the count
93  // to zero, we stop.
94  std::size_t old = count;
95  do { _fn(); } while (
96  !count.compare_exchange_strong(old, 0));
97  });
98  }
99  Dispatcher &_dispatcher;
100  Fn _fn;
101  };
102 
103  template <class Dispatcher, class Fn>
104  static std::function<void (std::atomic_size_t &)>
105  _MakeWaker(Dispatcher &d, Fn &&fn) {
106  return std::function<void (std::atomic_size_t &)>(
108  d, std::forward<Fn>(fn)));
109  }
110 
111  std::function<void (std::atomic_size_t &)> _waker;
112  std::atomic_size_t _count;
113 };
114 
116 
117 #endif // PXR_BASE_WORK_SINGULAR_TASK_H
type
Definition: core.h:556
WorkSingularTask(WorkDispatcher &d, Callable &&c, Args &&...args)
Definition: singularTask.h:63
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1425
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:74
**If you just want to fire and args
Definition: thread.h:618
WorkSingularTask & operator=(WorkSingularTask const &)=delete
GLint GLsizei count
Definition: glcorearb.h:405
WorkSingularTask(WorkSingularTask const &)=delete