From Jason Turner

[util.dynamic.safety]

C++14 → C++17 3.8 KB 45 lines
Current Draft | LaTeX Source
Archived: C++14 | C++17
Markdown: C++14 | C++17
Explore in Adventure Game

Diff to HTML by rtfpessoa

Files changed (1) hide show
  1. tmp/tmpx0oypm6m/{from.md → to.md} +22 -18
tmp/tmpx0oypm6m/{from.md → to.md} RENAMED
@@ -13,13 +13,12 @@ void declare_reachable(void* p);
13
  pointer ([[basic.stc.dynamic.safety]]) or a null pointer value.
14
 
15
  *Effects:* If `p` is not null, the complete object referenced by `p` is
16
  subsequently declared reachable ([[basic.stc.dynamic.safety]]).
17
 
18
- *Throws:* May throw `std::bad_alloc` if the system cannot allocate
19
- additional memory that may be required to track objects declared
20
- reachable.
21
 
22
  ``` cpp
23
  template <class T> T* undeclare_reachable(T* p);
24
  ```
25
 
@@ -31,38 +30,43 @@ live ([[basic.life]]) from the time of the call until the last
31
  *Returns:* A safely derived copy of `p` which shall compare equal to
32
  `p`.
33
 
34
  *Throws:* Nothing.
35
 
36
- It is expected that calls to `declare_reachable(p)` will consume a small
37
- amount of memory in addition to that occupied by the referenced object
38
- until the matching call to `undeclare_reachable(p)` is encountered. Long
39
- running programs should arrange that calls are matched.
 
40
 
41
  ``` cpp
42
  void declare_no_pointers(char* p, size_t n);
43
  ```
44
 
45
  *Requires:* No bytes in the specified range are currently registered
46
  with `declare_no_pointers()`. If the specified range is in an allocated
47
  object, then it must be entirely within a single allocated object. The
48
  object must be live until the corresponding `undeclare_no_pointers()`
49
- call. In a garbage-collecting implementation, the fact that a region in
50
- an object is registered with `declare_no_pointers()` should not prevent
51
- the object from being collected.
 
 
52
 
53
  *Effects:* The `n` bytes starting at `p` no longer contain traceable
54
  pointer locations, independent of their type. Hence indirection through
55
  a pointer located there is undefined if the object it points to was
56
  created by global `operator new` and not previously declared reachable.
57
- This may be used to inform a garbage collector or leak detector that
58
- this region of memory need not be traced.
 
59
 
60
  *Throws:* Nothing.
61
 
62
- Under some conditions implementations may need to allocate memory.
63
- However, the request can be ignored if memory allocation fails.
 
64
 
65
  ``` cpp
66
  void undeclare_no_pointers(char* p, size_t n);
67
  ```
68
 
@@ -78,10 +82,10 @@ ends.
78
  ``` cpp
79
  pointer_safety get_pointer_safety() noexcept;
80
  ```
81
 
82
  *Returns:* `pointer_safety::strict` if the implementation has strict
83
- pointer safety ([[basic.stc.dynamic.safety]]). It is implementation
84
- defined whether `get_pointer_safety` returns `pointer_safety::relaxed`
85
- or `pointer_safety::preferred` if the implementation has relaxed pointer
86
- safety.[^1]
87
 
 
13
  pointer ([[basic.stc.dynamic.safety]]) or a null pointer value.
14
 
15
  *Effects:* If `p` is not null, the complete object referenced by `p` is
16
  subsequently declared reachable ([[basic.stc.dynamic.safety]]).
17
 
18
+ *Throws:* May throw `bad_alloc` if the system cannot allocate additional
19
+ memory that may be required to track objects declared reachable.
 
20
 
21
  ``` cpp
22
  template <class T> T* undeclare_reachable(T* p);
23
  ```
24
 
 
30
  *Returns:* A safely derived copy of `p` which shall compare equal to
31
  `p`.
32
 
33
  *Throws:* Nothing.
34
 
35
+ [*Note 1*: It is expected that calls to `declare_reachable(p)` will
36
+ consume a small amount of memory in addition to that occupied by the
37
+ referenced object until the matching call to `undeclare_reachable(p)` is
38
+ encountered. Long running programs should arrange that calls are
39
+ matched. — *end note*]
40
 
41
  ``` cpp
42
  void declare_no_pointers(char* p, size_t n);
43
  ```
44
 
45
  *Requires:* No bytes in the specified range are currently registered
46
  with `declare_no_pointers()`. If the specified range is in an allocated
47
  object, then it must be entirely within a single allocated object. The
48
  object must be live until the corresponding `undeclare_no_pointers()`
49
+ call.
50
+
51
+ [*Note 2*: In a garbage-collecting implementation, the fact that a
52
+ region in an object is registered with `declare_no_pointers()` should
53
+ not prevent the object from being collected. — *end note*]
54
 
55
  *Effects:* The `n` bytes starting at `p` no longer contain traceable
56
  pointer locations, independent of their type. Hence indirection through
57
  a pointer located there is undefined if the object it points to was
58
  created by global `operator new` and not previously declared reachable.
59
+
60
+ [*Note 3*: This may be used to inform a garbage collector or leak
61
+ detector that this region of memory need not be traced. — *end note*]
62
 
63
  *Throws:* Nothing.
64
 
65
+ [*Note 4*: Under some conditions implementations may need to allocate
66
+ memory. However, the request can be ignored if memory allocation
67
+ fails. — *end note*]
68
 
69
  ``` cpp
70
  void undeclare_no_pointers(char* p, size_t n);
71
  ```
72
 
 
82
  ``` cpp
83
  pointer_safety get_pointer_safety() noexcept;
84
  ```
85
 
86
  *Returns:* `pointer_safety::strict` if the implementation has strict
87
+ pointer safety ([[basic.stc.dynamic.safety]]). It is
88
+ *implementation-defined* whether `get_pointer_safety` returns
89
+ `pointer_safety::relaxed` or `pointer_safety::preferred` if the
90
+ implementation has relaxed pointer safety.[^1]
91