boost_compat 0.1.0

Boost C++ library boost_compat packaged using Zanbil
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135

////
Copyright 2023 Christian Mazakas
Distributed under the Boost Software License, Version 1.0.
https://www.boost.org/LICENSE_1_0.txt
////

[#latch]
# <boost/compat/latch.hpp>
:idprefix: ref_latch_

## Description

The header `<boost/compat/latch.hpp>` implements, in a portable way, the C++20
`<latch>` header.

`latch` is a single-use barrier which counts downwards, enabling synchronization
between a set of threads. The counter can be manually decremented by any value,
but decrementing below zero causes undefined behavior. The maximum number of waiters is
specified to be `boost::compat::latch::max()`.

## Example

```cpp
std::ptrdiff_t const num_threads = 16;
boost::compat::latch l(num_threads);

std::vector<std::thread> threads;
for (int i = 0; i < num_threads; ++i) {
  threads.emplace_back([&l] {
    // do some preliminary work here...

    // block until all threads have reached this statement
    l.arrive_and_wait();

    // continue with further work...
  });
}

for (auto& t: threads) { t.join(); }
```

## Synopsis

```cpp
namespace boost
{
namespace compat
{

class latch {
  explicit latch(std::ptrdiff_t expected);

  latch(latch const &) = delete;
  latch &operator=(latch const &) = delete;

  ~latch() = default;

  void count_down(std::ptrdiff_t n = 1);
  bool try_wait() const noexcept;
  void wait() const;
  void arrive_and_wait(std::ptrdiff_t n = 1);

  static constexpr std::ptrdiff_t max() noexcept;
};

} // namespace compat
} // namespace boost
```

## Constructors

### Counter Constructor

```cpp
explicit latch(std::ptrdiff_t expected);
```

[horizontal]
Preconditions:;; `expected >= 0 && expected \<= boost::compat::latch::max()`.
Effects:;; Constructs a latch with an internal counter value of `expected`.

### Copy Constructor

```cpp
latch(latch const &) = delete;
```

`latch` is not copyable or movable.

## Member Functions

### count_down

```cpp
void count_down(std::ptrdiff_t n = 1);
```

[horizontal]
Preconditions:;; `n` must not be larger than the current internal counter's value.
Effects:;; Decrements the internal counter by `n`.

### try_wait

```cpp
bool try_wait() const noexcept;
```

Returns a boolean indicating whether or not the latch's internal counter has reached 0 (`true`) or not (`false`).

### wait

```cpp
void wait() const;
```

Blocks the current thread until the internal counter has reached 0.


### arrive_and_wait

```cpp
void arrive_and_wait(std::ptrdiff_t n = 1);
```

[horizontal]
Preconditions:;; `n` must not be larger than the current internal counter's value.
Effects:;; Decrements the internal counter by `n` and if the counter non-zero, blocks the current thread.

### max

```cpp
static constexpr std::ptrdiff_t max() noexcept;
```

Returns an implementation-defined number representing the maximum amount of waiters. Currently PTRDIFF_MAX.