From Jason Turner

[atomics.ref.generic]

C++20 → C++23 15.6 KB 162 lines
Current Draft | LaTeX Source
Archived: C++20 | C++23
Markdown: C++20 | C++23
Explore in Adventure Game

Diff to HTML by rtfpessoa

Files changed (1) hide show
  1. tmp/tmpounj8ps8/{from.md → to.md} +80 -73
tmp/tmpounj8ps8/{from.md → to.md} RENAMED
@@ -1,12 +1,15 @@
1
- ## Class template `atomic_ref` <a id="atomics.ref.generic">[[atomics.ref.generic]]</a>
 
 
2
 
3
  ``` cpp
4
  namespace std {
5
  template<class T> struct atomic_ref {
6
  private:
7
  T* ptr; // exposition only
 
8
  public:
9
  using value_type = T;
10
  static constexpr size_t required_alignment = implementation-defined // required alignment for atomic_ref type's operations;
11
 
12
  static constexpr bool is_always_lock_free = implementation-defined // whether a given atomic_ref type's operations are always lock free;
@@ -55,16 +58,16 @@ object.
55
 
56
  Atomic operations applied to an object through a referencing
57
  `atomic_ref` are atomic with respect to atomic operations applied
58
  through any other `atomic_ref` referencing the same object.
59
 
60
- [*Note 1*: Atomic operations or the `atomic_ref` constructor could
61
  acquire a shared resource, such as a lock associated with the referenced
62
  object, to enable atomic operations to be applied to the referenced
63
  object. — *end note*]
64
 
65
- ### Operations <a id="atomics.ref.ops">[[atomics.ref.ops]]</a>
66
 
67
  ``` cpp
68
  static constexpr size_t required_alignment;
69
  ```
70
 
@@ -251,94 +254,96 @@ void notify_all() const noexcept;
251
  `*ptr` that are eligible to be unblocked [[atomics.wait]] by this call.
252
 
253
  *Remarks:* This function is an atomic notifying
254
  operation [[atomics.wait]] on atomic object `*ptr`.
255
 
256
- ### Specializations for integral types <a id="atomics.ref.int">[[atomics.ref.int]]</a>
257
 
258
  There are specializations of the `atomic_ref` class template for the
259
  integral types `char`, `signed char`, `unsigned char`, `short`,
260
  `unsigned short`, `int`, `unsigned int`, `long`, `unsigned long`,
261
  `long long`, `unsigned long long`, `char8_t`, `char16_t`, `char32_t`,
262
  `wchar_t`, and any other types needed by the typedefs in the header
263
- `<cstdint>`. For each such type `integral`, the specialization
264
- `atomic_ref<integral>` provides additional atomic operations appropriate
265
- to integral types.
266
 
267
  [*Note 1*: The specialization `atomic_ref<bool>` uses the primary
268
  template [[atomics.ref.generic]]. — *end note*]
269
 
270
  ``` cpp
271
  namespace std {
272
- template<> struct atomic_ref<integral> {
273
  private:
274
- integral* ptr; // exposition only
 
275
  public:
276
- using value_type = integral;
277
  using difference_type = value_type;
278
  static constexpr size_t required_alignment = implementation-defined // required alignment for atomic_ref type's operations;
279
 
280
  static constexpr bool is_always_lock_free = implementation-defined // whether a given atomic_ref type's operations are always lock free;
281
  bool is_lock_free() const noexcept;
282
 
283
- explicit atomic_ref(integral&);
284
  atomic_ref(const atomic_ref&) noexcept;
285
  atomic_ref& operator=(const atomic_ref&) = delete;
286
 
287
- void store(integral, memory_order = memory_order::seq_cst) const noexcept;
288
- integral operator=(integral) const noexcept;
289
- integral load(memory_order = memory_order::seq_cst) const noexcept;
290
- operator integral() const noexcept;
291
 
292
- integral exchange(integral,
293
  memory_order = memory_order::seq_cst) const noexcept;
294
- bool compare_exchange_weak(integral&, integral,
295
  memory_order, memory_order) const noexcept;
296
- bool compare_exchange_strong(integral&, integral,
297
  memory_order, memory_order) const noexcept;
298
- bool compare_exchange_weak(integral&, integral,
299
  memory_order = memory_order::seq_cst) const noexcept;
300
- bool compare_exchange_strong(integral&, integral,
301
  memory_order = memory_order::seq_cst) const noexcept;
302
 
303
- integral fetch_add(integral,
304
  memory_order = memory_order::seq_cst) const noexcept;
305
- integral fetch_sub(integral,
306
  memory_order = memory_order::seq_cst) const noexcept;
307
- integral fetch_and(integral,
308
  memory_order = memory_order::seq_cst) const noexcept;
309
- integral fetch_or(integral,
310
  memory_order = memory_order::seq_cst) const noexcept;
311
- integral fetch_xor(integral,
312
  memory_order = memory_order::seq_cst) const noexcept;
313
 
314
- integral operator++(int) const noexcept;
315
- integral operator--(int) const noexcept;
316
- integral operator++() const noexcept;
317
- integral operator--() const noexcept;
318
- integral operator+=(integral) const noexcept;
319
- integral operator-=(integral) const noexcept;
320
- integral operator&=(integral) const noexcept;
321
- integral operator|=(integral) const noexcept;
322
- integral operator^=(integral) const noexcept;
323
 
324
- void wait(integral, memory_order = memory_order::seq_cst) const noexcept;
325
  void notify_one() const noexcept;
326
  void notify_all() const noexcept;
327
  };
328
  }
329
  ```
330
 
331
  Descriptions are provided below only for members that differ from the
332
  primary template.
333
 
334
- The following operations perform arithmetic computations. The key,
335
- operator, and computation correspondence is identified in
336
  [[atomic.types.int.comp]].
337
 
338
  ``` cpp
339
- integral fetch_key(integral operand, memory_order order = memory_order::seq_cst) const noexcept;
 
340
  ```
341
 
342
  *Effects:* Atomically replaces the value referenced by `*ptr` with the
343
  result of the computation applied to the value referenced by `*ptr` and
344
  the given operand. Memory is affected according to the value of `order`.
@@ -355,81 +360,82 @@ converted back to the signed type.
355
 
356
  [*Note 1*: There are no undefined results arising from the
357
  computation. — *end note*]
358
 
359
  ``` cpp
360
- integral operator op=(integral operand) const noexcept;
361
  ```
362
 
363
  *Effects:* Equivalent to:
364
  `return fetch_`*`key`*`(operand) `*`op`*` operand;`
365
 
366
- ### Specializations for floating-point types <a id="atomics.ref.float">[[atomics.ref.float]]</a>
367
 
368
- There are specializations of the `atomic_ref` class template for the
369
- floating-point types `float`, `double`, and `long double`. For each such
370
- type `floating-point`, the specialization `atomic_ref<floating-point>`
371
  provides additional atomic operations appropriate to floating-point
372
  types.
373
 
374
  ``` cpp
375
  namespace std {
376
- template<> struct atomic_ref<floating-point> {
377
  private:
378
- floating-point* ptr; // exposition only
 
379
  public:
380
- using value_type = floating-point;
381
  using difference_type = value_type;
382
  static constexpr size_t required_alignment = implementation-defined // required alignment for atomic_ref type's operations;
383
 
384
  static constexpr bool is_always_lock_free = implementation-defined // whether a given atomic_ref type's operations are always lock free;
385
  bool is_lock_free() const noexcept;
386
 
387
- explicit atomic_ref(floating-point&);
388
  atomic_ref(const atomic_ref&) noexcept;
389
  atomic_ref& operator=(const atomic_ref&) = delete;
390
 
391
- void store(floating-point, memory_order = memory_order::seq_cst) const noexcept;
392
- floating-point operator=(floating-point) const noexcept;
393
- floating-point load(memory_order = memory_order::seq_cst) const noexcept;
394
- operator floating-point() const noexcept;
395
 
396
- floating-point exchange(floating-point,
397
  memory_order = memory_order::seq_cst) const noexcept;
398
- bool compare_exchange_weak(floating-point&, floating-point,
399
  memory_order, memory_order) const noexcept;
400
- bool compare_exchange_strong(floating-point&, floating-point,
401
  memory_order, memory_order) const noexcept;
402
- bool compare_exchange_weak(floating-point&, floating-point,
403
  memory_order = memory_order::seq_cst) const noexcept;
404
- bool compare_exchange_strong(floating-point&, floating-point,
405
  memory_order = memory_order::seq_cst) const noexcept;
406
 
407
- floating-point fetch_add(floating-point,
408
  memory_order = memory_order::seq_cst) const noexcept;
409
- floating-point fetch_sub(floating-point,
410
  memory_order = memory_order::seq_cst) const noexcept;
411
 
412
- floating-point operator+=(floating-point) const noexcept;
413
- floating-point operator-=(floating-point) const noexcept;
414
 
415
- void wait(floating-point, memory_order = memory_order::seq_cst) const noexcept;
416
  void notify_one() const noexcept;
417
  void notify_all() const noexcept;
418
  };
419
  }
420
  ```
421
 
422
  Descriptions are provided below only for members that differ from the
423
  primary template.
424
 
425
- The following operations perform arithmetic computations. The key,
426
- operator, and computation correspondence are identified in
427
  [[atomic.types.int.comp]].
428
 
429
  ``` cpp
430
- floating-point fetch_key(floating-point operand,
431
  memory_order order = memory_order::seq_cst) const noexcept;
432
  ```
433
 
434
  *Effects:* Atomically replaces the value referenced by `*ptr` with the
435
  result of the computation applied to the value referenced by `*ptr` and
@@ -441,31 +447,32 @@ operations [[intro.races]].
441
  the effects.
442
 
443
  *Remarks:* If the result is not a representable value for its
444
  type [[expr.pre]], the result is unspecified, but the operations
445
  otherwise have no undefined behavior. Atomic arithmetic operations on
446
- *`floating-point`* should conform to the
447
- `std::numeric_limits<`*`floating-point`*`>` traits associated with the
448
- floating-point type [[limits.syn]]. The floating-point
449
  environment [[cfenv]] for atomic arithmetic operations on
450
- *`floating-point`* may be different than the calling thread’s
451
  floating-point environment.
452
 
453
  ``` cpp
454
- floating-point operator op=(floating-point operand) const noexcept;
455
  ```
456
 
457
  *Effects:* Equivalent to:
458
  `return fetch_`*`key`*`(operand) `*`op`*` operand;`
459
 
460
- ### Partial specialization for pointers <a id="atomics.ref.pointer">[[atomics.ref.pointer]]</a>
461
 
462
  ``` cpp
463
  namespace std {
464
  template<class T> struct atomic_ref<T*> {
465
  private:
466
  T** ptr; // exposition only
 
467
  public:
468
  using value_type = T*;
469
  using difference_type = ptrdiff_t;
470
  static constexpr size_t required_alignment = implementation-defined // required alignment for atomic_ref type's operations;
471
 
@@ -509,12 +516,12 @@ namespace std {
509
  ```
510
 
511
  Descriptions are provided below only for members that differ from the
512
  primary template.
513
 
514
- The following operations perform arithmetic computations. The key,
515
- operator, and computation correspondence is identified in
516
  [[atomic.types.pointer.comp]].
517
 
518
  ``` cpp
519
  T* fetch_key(difference_type operand, memory_order order = memory_order::seq_cst) const noexcept;
520
  ```
@@ -538,11 +545,11 @@ T* operator op=(difference_type operand) const noexcept;
538
  ```
539
 
540
  *Effects:* Equivalent to:
541
  `return fetch_`*`key`*`(operand) `*`op`*` operand;`
542
 
543
- ### Member operators common to integers and pointers to objects <a id="atomics.ref.memop">[[atomics.ref.memop]]</a>
544
 
545
  ``` cpp
546
  value_type operator++(int) const noexcept;
547
  ```
548
 
 
1
+ ### Class template `atomic_ref` <a id="atomics.ref.generic">[[atomics.ref.generic]]</a>
2
+
3
+ #### General <a id="atomics.ref.generic.general">[[atomics.ref.generic.general]]</a>
4
 
5
  ``` cpp
6
  namespace std {
7
  template<class T> struct atomic_ref {
8
  private:
9
  T* ptr; // exposition only
10
+
11
  public:
12
  using value_type = T;
13
  static constexpr size_t required_alignment = implementation-defined // required alignment for atomic_ref type's operations;
14
 
15
  static constexpr bool is_always_lock_free = implementation-defined // whether a given atomic_ref type's operations are always lock free;
 
58
 
59
  Atomic operations applied to an object through a referencing
60
  `atomic_ref` are atomic with respect to atomic operations applied
61
  through any other `atomic_ref` referencing the same object.
62
 
63
+ [*Note 1*: Atomic operations or the `atomic_ref` constructor can
64
  acquire a shared resource, such as a lock associated with the referenced
65
  object, to enable atomic operations to be applied to the referenced
66
  object. — *end note*]
67
 
68
+ #### Operations <a id="atomics.ref.ops">[[atomics.ref.ops]]</a>
69
 
70
  ``` cpp
71
  static constexpr size_t required_alignment;
72
  ```
73
 
 
254
  `*ptr` that are eligible to be unblocked [[atomics.wait]] by this call.
255
 
256
  *Remarks:* This function is an atomic notifying
257
  operation [[atomics.wait]] on atomic object `*ptr`.
258
 
259
+ #### Specializations for integral types <a id="atomics.ref.int">[[atomics.ref.int]]</a>
260
 
261
  There are specializations of the `atomic_ref` class template for the
262
  integral types `char`, `signed char`, `unsigned char`, `short`,
263
  `unsigned short`, `int`, `unsigned int`, `long`, `unsigned long`,
264
  `long long`, `unsigned long long`, `char8_t`, `char16_t`, `char32_t`,
265
  `wchar_t`, and any other types needed by the typedefs in the header
266
+ `<cstdint>`. For each such type `integral-type`, the specialization
267
+ `atomic_ref<integral-type>` provides additional atomic operations
268
+ appropriate to integral types.
269
 
270
  [*Note 1*: The specialization `atomic_ref<bool>` uses the primary
271
  template [[atomics.ref.generic]]. — *end note*]
272
 
273
  ``` cpp
274
  namespace std {
275
+ template<> struct atomic_ref<integral-type> {
276
  private:
277
+ integral-type* ptr; // exposition only
278
+
279
  public:
280
+ using value_type = integral-type;
281
  using difference_type = value_type;
282
  static constexpr size_t required_alignment = implementation-defined // required alignment for atomic_ref type's operations;
283
 
284
  static constexpr bool is_always_lock_free = implementation-defined // whether a given atomic_ref type's operations are always lock free;
285
  bool is_lock_free() const noexcept;
286
 
287
+ explicit atomic_ref(integral-type&);
288
  atomic_ref(const atomic_ref&) noexcept;
289
  atomic_ref& operator=(const atomic_ref&) = delete;
290
 
291
+ void store(integral-type, memory_order = memory_order::seq_cst) const noexcept;
292
+ integral-type operator=(integral-type) const noexcept;
293
+ integral-type load(memory_order = memory_order::seq_cst) const noexcept;
294
+ operator integral-type() const noexcept;
295
 
296
+ integral-type exchange(integral-type,
297
  memory_order = memory_order::seq_cst) const noexcept;
298
+ bool compare_exchange_weak(integral-type&, integral-type,
299
  memory_order, memory_order) const noexcept;
300
+ bool compare_exchange_strong(integral-type&, integral-type,
301
  memory_order, memory_order) const noexcept;
302
+ bool compare_exchange_weak(integral-type&, integral-type,
303
  memory_order = memory_order::seq_cst) const noexcept;
304
+ bool compare_exchange_strong(integral-type&, integral-type,
305
  memory_order = memory_order::seq_cst) const noexcept;
306
 
307
+ integral-type fetch_add(integral-type,
308
  memory_order = memory_order::seq_cst) const noexcept;
309
+ integral-type fetch_sub(integral-type,
310
  memory_order = memory_order::seq_cst) const noexcept;
311
+ integral-type fetch_and(integral-type,
312
  memory_order = memory_order::seq_cst) const noexcept;
313
+ integral-type fetch_or(integral-type,
314
  memory_order = memory_order::seq_cst) const noexcept;
315
+ integral-type fetch_xor(integral-type,
316
  memory_order = memory_order::seq_cst) const noexcept;
317
 
318
+ integral-type operator++(int) const noexcept;
319
+ integral-type operator--(int) const noexcept;
320
+ integral-type operator++() const noexcept;
321
+ integral-type operator--() const noexcept;
322
+ integral-type operator+=(integral-type) const noexcept;
323
+ integral-type operator-=(integral-type) const noexcept;
324
+ integral-type operator&=(integral-type) const noexcept;
325
+ integral-type operator|=(integral-type) const noexcept;
326
+ integral-type operator^=(integral-type) const noexcept;
327
 
328
+ void wait(integral-type, memory_order = memory_order::seq_cst) const noexcept;
329
  void notify_one() const noexcept;
330
  void notify_all() const noexcept;
331
  };
332
  }
333
  ```
334
 
335
  Descriptions are provided below only for members that differ from the
336
  primary template.
337
 
338
+ The following operations perform arithmetic computations. The
339
+ correspondence among key, operator, and computation is specified in
340
  [[atomic.types.int.comp]].
341
 
342
  ``` cpp
343
+ integral-type fetch_key(integral-type operand,
344
+ memory_order order = memory_order::seq_cst) const noexcept;
345
  ```
346
 
347
  *Effects:* Atomically replaces the value referenced by `*ptr` with the
348
  result of the computation applied to the value referenced by `*ptr` and
349
  the given operand. Memory is affected according to the value of `order`.
 
360
 
361
  [*Note 1*: There are no undefined results arising from the
362
  computation. — *end note*]
363
 
364
  ``` cpp
365
+ integral-type operator op=(integral-type operand) const noexcept;
366
  ```
367
 
368
  *Effects:* Equivalent to:
369
  `return fetch_`*`key`*`(operand) `*`op`*` operand;`
370
 
371
+ #### Specializations for floating-point types <a id="atomics.ref.float">[[atomics.ref.float]]</a>
372
 
373
+ There are specializations of the `atomic_ref` class template for all
374
+ cv-unqualified floating-point types. For each such type
375
+ `floating-point-type`, the specialization `atomic_ref<floating-point>`
376
  provides additional atomic operations appropriate to floating-point
377
  types.
378
 
379
  ``` cpp
380
  namespace std {
381
+ template<> struct atomic_ref<floating-point-type> {
382
  private:
383
+ floating-point-type* ptr; // exposition only
384
+
385
  public:
386
+ using value_type = floating-point-type;
387
  using difference_type = value_type;
388
  static constexpr size_t required_alignment = implementation-defined // required alignment for atomic_ref type's operations;
389
 
390
  static constexpr bool is_always_lock_free = implementation-defined // whether a given atomic_ref type's operations are always lock free;
391
  bool is_lock_free() const noexcept;
392
 
393
+ explicit atomic_ref(floating-point-type&);
394
  atomic_ref(const atomic_ref&) noexcept;
395
  atomic_ref& operator=(const atomic_ref&) = delete;
396
 
397
+ void store(floating-point-type, memory_order = memory_order::seq_cst) const noexcept;
398
+ floating-point-type operator=(floating-point-type) const noexcept;
399
+ floating-point-type load(memory_order = memory_order::seq_cst) const noexcept;
400
+ operator floating-point-type() const noexcept;
401
 
402
+ floating-point-type exchange(floating-point-type,
403
  memory_order = memory_order::seq_cst) const noexcept;
404
+ bool compare_exchange_weak(floating-point-type&, floating-point-type,
405
  memory_order, memory_order) const noexcept;
406
+ bool compare_exchange_strong(floating-point-type&, floating-point-type,
407
  memory_order, memory_order) const noexcept;
408
+ bool compare_exchange_weak(floating-point-type&, floating-point-type,
409
  memory_order = memory_order::seq_cst) const noexcept;
410
+ bool compare_exchange_strong(floating-point-type&, floating-point-type,
411
  memory_order = memory_order::seq_cst) const noexcept;
412
 
413
+ floating-point-type fetch_add(floating-point-type,
414
  memory_order = memory_order::seq_cst) const noexcept;
415
+ floating-point-type fetch_sub(floating-point-type,
416
  memory_order = memory_order::seq_cst) const noexcept;
417
 
418
+ floating-point-type operator+=(floating-point-type) const noexcept;
419
+ floating-point-type operator-=(floating-point-type) const noexcept;
420
 
421
+ void wait(floating-point-type, memory_order = memory_order::seq_cst) const noexcept;
422
  void notify_one() const noexcept;
423
  void notify_all() const noexcept;
424
  };
425
  }
426
  ```
427
 
428
  Descriptions are provided below only for members that differ from the
429
  primary template.
430
 
431
+ The following operations perform arithmetic computations. The
432
+ correspondence among key, operator, and computation is specified in
433
  [[atomic.types.int.comp]].
434
 
435
  ``` cpp
436
+ floating-point-type fetch_key(floating-point-type operand,
437
  memory_order order = memory_order::seq_cst) const noexcept;
438
  ```
439
 
440
  *Effects:* Atomically replaces the value referenced by `*ptr` with the
441
  result of the computation applied to the value referenced by `*ptr` and
 
447
  the effects.
448
 
449
  *Remarks:* If the result is not a representable value for its
450
  type [[expr.pre]], the result is unspecified, but the operations
451
  otherwise have no undefined behavior. Atomic arithmetic operations on
452
+ *`floating-point-type`* should conform to the
453
+ `std::numeric_limits<`*`floating-point-type`*`>` traits associated with
454
+ the floating-point type [[limits.syn]]. The floating-point
455
  environment [[cfenv]] for atomic arithmetic operations on
456
+ *`floating-point-type`* may be different than the calling thread’s
457
  floating-point environment.
458
 
459
  ``` cpp
460
+ floating-point-type operator op=(floating-point-type operand) const noexcept;
461
  ```
462
 
463
  *Effects:* Equivalent to:
464
  `return fetch_`*`key`*`(operand) `*`op`*` operand;`
465
 
466
+ #### Partial specialization for pointers <a id="atomics.ref.pointer">[[atomics.ref.pointer]]</a>
467
 
468
  ``` cpp
469
  namespace std {
470
  template<class T> struct atomic_ref<T*> {
471
  private:
472
  T** ptr; // exposition only
473
+
474
  public:
475
  using value_type = T*;
476
  using difference_type = ptrdiff_t;
477
  static constexpr size_t required_alignment = implementation-defined // required alignment for atomic_ref type's operations;
478
 
 
516
  ```
517
 
518
  Descriptions are provided below only for members that differ from the
519
  primary template.
520
 
521
+ The following operations perform arithmetic computations. The
522
+ correspondence among key, operator, and computation is specified in
523
  [[atomic.types.pointer.comp]].
524
 
525
  ``` cpp
526
  T* fetch_key(difference_type operand, memory_order order = memory_order::seq_cst) const noexcept;
527
  ```
 
545
  ```
546
 
547
  *Effects:* Equivalent to:
548
  `return fetch_`*`key`*`(operand) `*`op`*` operand;`
549
 
550
+ #### Member operators common to integers and pointers to objects <a id="atomics.ref.memop">[[atomics.ref.memop]]</a>
551
 
552
  ``` cpp
553
  value_type operator++(int) const noexcept;
554
  ```
555