Skip to content

Commit b889530

Browse files
schlangsterschlangster
committed
Documentation + cleanup.
1 parent b453318 commit b889530

5 files changed

Lines changed: 43 additions & 11 deletions

File tree

‎include/react/algorithm.h‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@
2424
/*****************************************/ REACT_BEGIN /*****************************************/
2525

2626
///////////////////////////////////////////////////////////////////////////////////////////////////
27-
/// Hold the most recent event in a state
27+
/// Holds the most recent event in a state
2828
///////////////////////////////////////////////////////////////////////////////////////////////////
2929
template <typename T, typename E>
3030
auto Hold(const Group& group, T&& initialValue, const Event<E>& evnt) -> State<E>
@@ -60,7 +60,7 @@ auto Monitor(const State<S>& state) -> Event<S>
6060
{ return Monitor(state.GetGroup(), state); }
6161

6262
///////////////////////////////////////////////////////////////////////////////////////////////////
63-
/// Iterate - Iteratively combines state value with values from event stream (aka Fold)
63+
/// Iteratively combines state value with values from event stream (aka Fold)
6464
///////////////////////////////////////////////////////////////////////////////////////////////////
6565
template <typename S, typename T, typename F, typename E>
6666
auto Iterate(const Group& group, T&& initialValue, F&& func, const Event<E>& evnt) -> State<S>

‎include/react/common/ptrcache.h‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,12 +18,16 @@
1818
/*****************************************/ REACT_BEGIN /*****************************************/
1919

2020
///////////////////////////////////////////////////////////////////////////////////////////////////
21-
/// Stores weak pointers to V indexed by K.
21+
/// A cache to objects of type shared_ptr<V> that stores weak pointers.
22+
/// Thread-safe.
2223
///////////////////////////////////////////////////////////////////////////////////////////////////
2324
template <typename K, typename V>
2425
class WeakPtrCache
2526
{
2627
public:
28+
/// Returns a shared pointer to an object that existings in the cache, indexed by key.
29+
/// If no hit was found, createFunc is used to construct the object managed by shared pointer.
30+
/// A weak pointer to the result is stored in the cache.
2731
template <typename F>
2832
std::shared_ptr<V> LookupOrCreate(const K& key, F&& createFunc)
2933
{
@@ -32,6 +36,8 @@ class WeakPtrCache
3236
auto it = map_.find(key);
3337
if (it != map_.end())
3438
{
39+
// Lock fails, if the object was cached before, but has been released already.
40+
// In that case we re-create it.
3541
if (auto ptr = it->second.lock())
3642
{
3743
return ptr;
@@ -43,6 +49,7 @@ class WeakPtrCache
4349
return v;
4450
}
4551

52+
/// Removes an entry from the cache.
4653
void Erase(const K& key)
4754
{
4855
std::lock_guard<std::mutex> scopedLock(mutex_);

‎include/react/common/slotmap.h‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,8 @@
2020
/*****************************************/ REACT_BEGIN /*****************************************/
2121

2222
///////////////////////////////////////////////////////////////////////////////////////////////////
23-
/// SlotMap
23+
/// A simple slot map.
24+
/// Insert returns the slot index, which stays valid until the element is erased.
2425
///////////////////////////////////////////////////////////////////////////////////////////////////
2526
template <typename T>
2627
class SlotMap

‎include/react/common/syncpoint.h‎

Lines changed: 26 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,16 @@
2222
/*****************************************/ REACT_BEGIN /*****************************************/
2323

2424
///////////////////////////////////////////////////////////////////////////////////////////////////
25-
/// SyncPoint
25+
/// A synchronization primitive that is essentially a cooperative semaphore, i.e. it blocks a
26+
/// consumer until all producers are done.
27+
/// Usage:
28+
/// SyncPoint sp;
29+
/// // Add a dependency the sync point should wait for. The depenency is released on destruction.
30+
/// SyncPoint::Depenency dep(sp);
31+
/// // Pass dependency to some operation. Dependencies can be copied as well.
32+
/// SomeAsyncOperation(std::move(dep));
33+
/// // Wait until all dependencies are released.
34+
/// sp.Wait()
2635
///////////////////////////////////////////////////////////////////////////////////////////////////
2736
class SyncPoint
2837
{
@@ -104,6 +113,7 @@ class SyncPoint
104113
};
105114

106115
public:
116+
/// Creates a sync point.
107117
SyncPoint() :
108118
state_( std::make_shared<SyncPointState>() )
109119
{ }
@@ -116,36 +126,42 @@ class SyncPoint
116126

117127
SyncPoint& operator=(SyncPoint&&) = default;
118128

129+
/// Blocks the calling thread until all dependencies of this sync point are released.
119130
void Wait()
120131
{
121132
state_->Wait();
122133
}
123134

135+
/// Like Wait, but times out after relTime. Returns false if the timeout was hit.
124136
template <typename TRep, typename TPeriod>
125137
bool WaitFor(const std::chrono::duration<TRep, TPeriod>& relTime)
126138
{
127139
return state_->WaitFor(relTime);
128140
}
129141

142+
/// Like Wait, but times out at relTime. Returns false if the timeout was hit.
130143
template <typename TRep, typename TPeriod>
131144
bool WaitUntil(const std::chrono::duration<TRep, TPeriod>& relTime)
132145
{
133146
return state_->WaitUntil(relTime);
134147
}
135148

149+
/// A RAII-style token object that represents a dependency of a SyncPoint.
136150
class Dependency
137151
{
138152
public:
153+
/// Constructs an unbound dependency.
139154
Dependency() = default;
140155

141-
// Construct from single sync point.
156+
/// Constructs a single dependency for a sync point.
142157
explicit Dependency(const SyncPoint& sp) :
143158
target_( sp.state_ )
144159
{
145160
target_->IncrementWaitCount();
146161
}
147162

148-
// Construct from vector of other dependencies.
163+
/// Merges an input range of other dependencies into a single dependency.
164+
/// This allows to create APIs that are agnostic of how many dependent operations they process.
149165
template <typename TBegin, typename TEnd>
150166
Dependency(TBegin first, TEnd last)
151167
{
@@ -172,6 +188,8 @@ class SyncPoint
172188
}
173189
}
174190

191+
/// Copy constructor and assignment split a dependency.
192+
/// The new dependency that has the same target(s) as other.
175193
Dependency(const Dependency& other) :
176194
target_( other.target_ )
177195
{
@@ -191,6 +209,8 @@ class SyncPoint
191209
return *this;
192210
}
193211

212+
/// Move constructor and assignment transfer a dependency.
213+
/// The moved from object is left unbound.
194214
Dependency(Dependency&& other) :
195215
target_( std::move(other.target_) )
196216
{ }
@@ -204,12 +224,14 @@ class SyncPoint
204224
return *this;
205225
}
206226

227+
/// The destructor releases a dependency, if it's not unbound.
207228
~Dependency()
208229
{
209230
if (target_)
210231
target_->DecrementWaitCount();
211232
}
212233

234+
/// Manually releases the dependency. Afterwards it is unbound.
213235
void Release()
214236
{
215237
if (target_)
@@ -219,6 +241,7 @@ class SyncPoint
219241
}
220242
}
221243

244+
/// Returns if a dependency is released, i.e. if it is unbound.
222245
bool IsReleased() const
223246
{ return target_ == nullptr; }
224247

‎include/react/common/utility.h‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,7 @@ struct Apply<0>
3838
}
3939
};
4040

41+
/// Use until C++17 std::apply is available.
4142
template<typename F, typename T>
4243
inline auto apply(F&& f, T&& t) -> decltype(auto)
4344
{
@@ -61,10 +62,12 @@ bool IsBitmaskSet(T flags, T mask)
6162

6263
/****************************************/ REACT_IMPL_END /***************************************/
6364

64-
// Expand args by wrapping them in a dummy function
65-
// Use comma operator to replace potential void return value with 0
65+
/// Expand args by wrapping them in a dummy function
66+
/// Use comma operator to replace potential void return value with 0
67+
/// Bware that order of calls is unspecified.
6668
#define REACT_EXPAND_PACK(...) REACT_IMPL::pass((__VA_ARGS__ , 0) ...)
6769

70+
/// Bitmask helpers
6871
#define REACT_DEFINE_BITMASK_OPERATORS(t) \
6972
inline t operator|(t lhs, t rhs) \
7073
{ return static_cast<t>(static_cast<std::underlying_type<t>::type>(lhs) | static_cast<std::underlying_type<t>::type>(rhs)); } \
@@ -81,6 +84,4 @@ bool IsBitmaskSet(T flags, T mask)
8184
inline t& operator^=(t& lhs, t rhs) \
8285
{ lhs = static_cast<t>(static_cast<std::underlying_type<t>::type>(lhs) ^ static_cast<std::underlying_type<t>::type>(rhs)); return lhs; }
8386

84-
// Bitmask helper
85-
8687
#endif // REACT_COMMON_UTIL_H_INCLUDED

0 commit comments

Comments
 (0)