commit ce7c66e2d0ccaf0265f2c2afce9824c9b9ae6123 (tree)
parent 1b8e6b8ba9c6a0f52e2d823218732bb2dc8a0362
Author: Andrew Kelley <andrew@ziglang.org>
Date: Sun, 21 Jan 2024 20:39:50 -0700
langref: make more consistent
* moves some langref into std.builtin doc comments
* use the same way of referencing stuff from std.builtin
closes #16483
Diffstat:
2 files changed, 35 insertions(+), 64 deletions(-)
diff --git a/doc/langref.html.in b/doc/langref.html.in
@@ -7754,7 +7754,7 @@ comptime {
{#header_close#}
{#header_open|@atomicLoad#}
- <pre>{#syntax#}@atomicLoad(comptime T: type, ptr: *const T, comptime ordering: builtin.AtomicOrder) T{#endsyntax#}</pre>
+ <pre>{#syntax#}@atomicLoad(comptime T: type, ptr: *const T, comptime ordering: AtomicOrder) T{#endsyntax#}</pre>
<p>
This builtin function atomically dereferences a pointer to a {#syntax#}T{#endsyntax#} and returns the value.
</p>
@@ -7762,11 +7762,12 @@ comptime {
{#syntax#}T{#endsyntax#} must be a pointer, a {#syntax#}bool{#endsyntax#}, a float,
an integer or an enum.
</p>
+ <p>{#syntax#}AtomicOrder{#endsyntax#} can be found with {#syntax#}@import("std").builtin.AtomicOrder{#endsyntax#}.</p>
{#see_also|@atomicStore|@atomicRmw|@fence|@cmpxchgWeak|@cmpxchgStrong#}
{#header_close#}
{#header_open|@atomicRmw#}
- <pre>{#syntax#}@atomicRmw(comptime T: type, ptr: *T, comptime op: builtin.AtomicRmwOp, operand: T, comptime ordering: builtin.AtomicOrder) T{#endsyntax#}</pre>
+ <pre>{#syntax#}@atomicRmw(comptime T: type, ptr: *T, comptime op: AtomicRmwOp, operand: T, comptime ordering: AtomicOrder) T{#endsyntax#}</pre>
<p>
This builtin function dereferences a pointer to a {#syntax#}T{#endsyntax#} and atomically
modifies the value and returns the previous value.
@@ -7775,27 +7776,13 @@ comptime {
{#syntax#}T{#endsyntax#} must be a pointer, a {#syntax#}bool{#endsyntax#}, a float,
an integer or an enum.
</p>
- <p>
- Supported values for the {#syntax#}op{#endsyntax#} parameter:
- </p>
- <ul>
- <li>{#syntax#}.Xchg{#endsyntax#} - stores the operand unmodified. Supports enums, integers and floats.</li>
- <li>{#syntax#}.Add{#endsyntax#} - for integers, twos complement wraparound addition.
- Also supports {#link|Floats#}.</li>
- <li>{#syntax#}.Sub{#endsyntax#} - for integers, twos complement wraparound subtraction.
- Also supports {#link|Floats#}.</li>
- <li>{#syntax#}.And{#endsyntax#} - bitwise and</li>
- <li>{#syntax#}.Nand{#endsyntax#} - bitwise nand</li>
- <li>{#syntax#}.Or{#endsyntax#} - bitwise or</li>
- <li>{#syntax#}.Xor{#endsyntax#} - bitwise xor</li>
- <li>{#syntax#}.Max{#endsyntax#} - stores the operand if it is larger. Supports integers and floats.</li>
- <li>{#syntax#}.Min{#endsyntax#} - stores the operand if it is smaller. Supports integers and floats.</li>
- </ul>
+ <p>{#syntax#}AtomicOrder{#endsyntax#} can be found with {#syntax#}@import("std").builtin.AtomicOrder{#endsyntax#}.</p>
+ <p>{#syntax#}AtomicRmwOp{#endsyntax#} can be found with {#syntax#}@import("std").builtin.AtomicRmwOp{#endsyntax#}.</p>
{#see_also|@atomicStore|@atomicLoad|@fence|@cmpxchgWeak|@cmpxchgStrong#}
{#header_close#}
{#header_open|@atomicStore#}
- <pre>{#syntax#}@atomicStore(comptime T: type, ptr: *T, value: T, comptime ordering: builtin.AtomicOrder) void{#endsyntax#}</pre>
+ <pre>{#syntax#}@atomicStore(comptime T: type, ptr: *T, value: T, comptime ordering: AtomicOrder) void{#endsyntax#}</pre>
<p>
This builtin function dereferences a pointer to a {#syntax#}T{#endsyntax#} and atomically stores the given value.
</p>
@@ -7803,6 +7790,7 @@ comptime {
{#syntax#}T{#endsyntax#} must be a pointer, a {#syntax#}bool{#endsyntax#}, a float,
an integer or an enum.
</p>
+ <p>{#syntax#}AtomicOrder{#endsyntax#} can be found with {#syntax#}@import("std").builtin.AtomicOrder{#endsyntax#}.</p>
{#see_also|@atomicLoad|@atomicRmw|@fence|@cmpxchgWeak|@cmpxchgStrong#}
{#header_close#}
@@ -8079,6 +8067,7 @@ fn cmpxchgStrongButNotAtomic(comptime T: type, ptr: *T, expected_value: T, new_v
an integer or an enum.
</p>
<p>{#syntax#}@typeInfo(@TypeOf(ptr)).Pointer.alignment{#endsyntax#} must be {#syntax#}>= @sizeOf(T).{#endsyntax#}</p>
+ <p>{#syntax#}AtomicOrder{#endsyntax#} can be found with {#syntax#}@import("std").builtin.AtomicOrder{#endsyntax#}.</p>
{#see_also|@atomicStore|@atomicLoad|@atomicRmw|@fence|@cmpxchgWeak#}
{#header_close#}
@@ -8110,6 +8099,7 @@ fn cmpxchgWeakButNotAtomic(comptime T: type, ptr: *T, expected_value: T, new_val
an integer or an enum.
</p>
<p>{#syntax#}@typeInfo(@TypeOf(ptr)).Pointer.alignment{#endsyntax#} must be {#syntax#}>= @sizeOf(T).{#endsyntax#}</p>
+ <p>{#syntax#}AtomicOrder{#endsyntax#} can be found with {#syntax#}@import("std").builtin.AtomicOrder{#endsyntax#}.</p>
{#see_also|@atomicStore|@atomicLoad|@atomicRmw|@fence|@cmpxchgStrong#}
{#header_close#}
@@ -8400,9 +8390,7 @@ export fn @"A function name that is a complete sentence."() void {}
<p>
The {#syntax#}fence{#endsyntax#} function is used to introduce happens-before edges between operations.
</p>
- <p>
- {#syntax#}AtomicOrder{#endsyntax#} can be found with {#syntax#}@import("std").builtin.AtomicOrder{#endsyntax#}.
- </p>
+ <p>{#syntax#}AtomicOrder{#endsyntax#} can be found with {#syntax#}@import("std").builtin.AtomicOrder{#endsyntax#}.</p>
{#see_also|@atomicStore|@atomicLoad|@atomicRmw|@cmpxchgWeak|@cmpxchgStrong#}
{#header_close#}
@@ -8810,7 +8798,7 @@ test "@wasmMemoryGrow" {
{#header_close#}
{#header_open|@prefetch#}
- <pre>{#syntax#}@prefetch(ptr: anytype, comptime options: std.builtin.PrefetchOptions) void{#endsyntax#}</pre>
+ <pre>{#syntax#}@prefetch(ptr: anytype, comptime options: PrefetchOptions) void{#endsyntax#}</pre>
<p>
This builtin tells the compiler to emit a prefetch instruction if supported by the
target CPU. If the target CPU does not support the requested prefetch instruction,
@@ -8822,37 +8810,7 @@ test "@wasmMemoryGrow" {
address to prefetch. This function does not dereference the pointer, it is perfectly legal
to pass a pointer to invalid memory to this function and no illegal behavior will result.
</p>
- <p>
- The {#syntax#}options{#endsyntax#} argument is the following struct:
- </p>
- {#code_begin|syntax|builtin#}
-/// This data structure is used by the Zig language code generation and
-/// therefore must be kept in sync with the compiler implementation.
-pub const PrefetchOptions = struct {
- /// Whether the prefetch should prepare for a read or a write.
- rw: Rw = .read,
- /// The data's locality in an inclusive range from 0 to 3.
- ///
- /// 0 means no temporal locality. That is, the data can be immediately
- /// dropped from the cache after it is accessed.
- ///
- /// 3 means high temporal locality. That is, the data should be kept in
- /// the cache as it is likely to be accessed again soon.
- locality: u2 = 3,
- /// The cache that the prefetch should be preformed on.
- cache: Cache = .data,
-
- pub const Rw = enum(u1) {
- read,
- write,
- };
-
- pub const Cache = enum(u1) {
- instruction,
- data,
- };
-};
- {#code_end#}
+ <p>{#syntax#}PrefetchOptions{#endsyntax#} can be found with {#syntax#}@import("std").builtin.PrefetchOptions{#endsyntax#}.</p>
{#header_close#}
{#header_open|@ptrCast#}
@@ -8981,16 +8939,8 @@ test "foo" {
{#header_close#}
{#header_open|@setFloatMode#}
- <pre>{#syntax#}@setFloatMode(comptime mode: @import("std").builtin.FloatMode) void{#endsyntax#}</pre>
- <p>
- Sets the floating point mode of the current scope. Possible values are:
- </p>
- {#code_begin|syntax|FloatMode#}
-pub const FloatMode = enum {
- Strict,
- Optimized,
-};
- {#code_end#}
+ <pre>{#syntax#}@setFloatMode(comptime mode: FloatMode) void{#endsyntax#}</pre>
+ <p>Changes the current scope's rules about how floating point operations are defined.</p>
<ul>
<li>
{#syntax#}Strict{#endsyntax#} (default) - Floating point operations follow strict IEEE compliance.
@@ -9012,6 +8962,7 @@ pub const FloatMode = enum {
The floating point mode is inherited by child scopes, and can be overridden in any scope.
You can set the floating point mode in a struct or module scope by using a comptime block.
</p>
+ <p>{#syntax#}FloatMode{#endsyntax#} can be found with {#syntax#}@import("std").builtin.FloatMode{#endsyntax#}.</p>
{#see_also|Floating Point Operations#}
{#header_close#}
diff --git a/lib/std/builtin.zig b/lib/std/builtin.zig
@@ -102,14 +102,34 @@ pub const ReduceOp = enum {
/// This data structure is used by the Zig language code generation and
/// therefore must be kept in sync with the compiler implementation.
pub const AtomicRmwOp = enum {
+ /// Exchange - store the operand unmodified.
+ /// Supports enums, integers, and floats.
Xchg,
+ /// Add operand to existing value.
+ /// Supports integers and floats.
+ /// For integers, two's complement wraparound applies.
Add,
+ /// Subtract operand from existing value.
+ /// Supports integers and floats.
+ /// For integers, two's complement wraparound applies.
Sub,
+ /// Perform bitwise AND on existing value with operand.
+ /// Supports integers.
And,
+ /// Perform bitwise NAND on existing value with operand.
+ /// Supports integers.
Nand,
+ /// Perform bitwise OR on existing value with operand.
+ /// Supports integers.
Or,
+ /// Perform bitwise XOR on existing value with operand.
+ /// Supports integers.
Xor,
+ /// Store operand if it is larger than the existing value.
+ /// Supports integers and floats.
Max,
+ /// Store operand if it is smaller than the existing value.
+ /// Supports integers and floats.
Min,
};
