diff --git a/doc/langref.html.in b/doc/langref.html.in index c095ab0518..bf2a6fd71d 100644 --- a/doc/langref.html.in +++ b/doc/langref.html.in @@ -1179,33 +1179,8 @@ test "this will be skipped" { return error.SkipZigTest; } {#code_end#} -
- The default test runner skips tests containing a {#link|suspend point|Async Functions#} while the - test is running using the default, blocking IO mode. - (The evented IO mode is enabled using the --test-evented-io command line parameter.) -
- {#code_begin|test|async_skip#} - {#backend_stage1#} -const std = @import("std"); - -test "async skip test" { - var frame = async func(); - const result = await frame; - try std.testing.expect(result == 1); -} - -fn func() i32 { - suspend { - resume @frame(); - } - return 1; -} - {#code_end#} -- In the code sample above, the test would not be skipped in blocking IO mode if the {#syntax#}nosuspend{#endsyntax#} - keyword was used (see {#link|Async and Await#}). -
{#header_close#} + {#header_open|Report Memory Leaks#}When code allocates {#link|Memory#} using the {#link|Zig Standard Library#}'s testing allocator, @@ -6288,7 +6263,6 @@ test "float widening" {
TODO: @atomic rmw
TODO: builtin atomic memory ordering enum
{#header_close#} + {#header_open|Async Functions#} -- When a function is called, a frame is pushed to the stack, - the function runs until it reaches a return statement, and then the frame is popped from the stack. - The code following the callsite does not run until the function returns. -
-- An async function is a function whose execution is split into an {#syntax#}async{#endsyntax#} initiation, - followed by an {#syntax#}await{#endsyntax#} completion. Its frame is - provided explicitly by the caller, and it can be suspended and resumed any number of times. -
-- The code following the {#syntax#}async{#endsyntax#} callsite runs immediately after the async - function first suspends. When the return value of the async function is needed, - the calling code can {#syntax#}await{#endsyntax#} on the async function frame. - This will suspend the calling code until the async function completes, at which point - execution resumes just after the {#syntax#}await{#endsyntax#} callsite. -
-- Zig infers that a function is {#syntax#}async{#endsyntax#} when it observes that the function contains - a suspension point. Async functions can be called the same as normal functions. A - function call of an async function is a suspend point. -
- {#header_open|Suspend and Resume#} -- At any point, a function may suspend itself. This causes control flow to - return to the callsite (in the case of the first suspension), - or resumer (in the case of subsequent suspensions). -
- {#code_begin|test|suspend_no_resume#} - {#backend_stage1#} -const std = @import("std"); -const expect = std.testing.expect; - -var x: i32 = 1; - -test "suspend with no resume" { - var frame = async func(); - try expect(x == 2); - _ = frame; -} - -fn func() void { - x += 1; - suspend {} - // This line is never reached because the suspend has no matching resume. - x += 1; -} - {#code_end#} -- In the same way that each allocation should have a corresponding free, - Each {#syntax#}suspend{#endsyntax#} should have a corresponding {#syntax#}resume{#endsyntax#}. - A suspend block allows a function to put a pointer to its own - frame somewhere, for example into an event loop, even if that action will perform a - {#syntax#}resume{#endsyntax#} operation on a different thread. - {#link|@frame#} provides access to the async function frame pointer. -
- {#code_begin|test|async_suspend_block#} - {#backend_stage1#} -const std = @import("std"); -const expect = std.testing.expect; - -var the_frame: anyframe = undefined; -var result = false; - -test "async function suspend with block" { - _ = async testSuspendBlock(); - try expect(!result); - resume the_frame; - try expect(result); -} - -fn testSuspendBlock() void { - suspend { - comptime try expect(@TypeOf(@frame()) == *@Frame(testSuspendBlock)); - the_frame = @frame(); - } - result = true; -} - {#code_end#} -- {#syntax#}suspend{#endsyntax#} causes a function to be {#syntax#}async{#endsyntax#}. -
- - {#header_open|Resuming from Suspend Blocks#} -- Upon entering a {#syntax#}suspend{#endsyntax#} block, the async function is already considered - suspended, and can be resumed. For example, if you started another kernel thread, - and had that thread call {#syntax#}resume{#endsyntax#} on the frame pointer provided by the - {#link|@frame#}, the new thread would begin executing after the suspend - block, while the old thread continued executing the suspend block. -
-- However, the async function can be directly resumed from the suspend block, in which case it - never returns to its resumer and continues executing. -
- {#code_begin|test|resume_from_suspend#} - {#backend_stage1#} -const std = @import("std"); -const expect = std.testing.expect; - -test "resume from suspend" { - var my_result: i32 = 1; - _ = async testResumeFromSuspend(&my_result); - try std.testing.expect(my_result == 2); -} -fn testResumeFromSuspend(my_result: *i32) void { - suspend { - resume @frame(); - } - my_result.* += 1; - suspend {} - my_result.* += 1; -} - {#code_end#} -- This is guaranteed to tail call, and therefore will not cause a new stack frame. -
- {#header_close#} +Async functions are being temporarily regressed and will be
+ restored before Zig
+ 0.11.0 is tagged. I apologize for the instability. Please use Zig 0.10.0 with
+ the -fstage1 flag for now if you need this feature.
- In the same way that every {#syntax#}suspend{#endsyntax#} has a matching - {#syntax#}resume{#endsyntax#}, every {#syntax#}async{#endsyntax#} has a matching {#syntax#}await{#endsyntax#} - in standard code. -
-- However, it is possible to have an {#syntax#}async{#endsyntax#} call - without a matching {#syntax#}await{#endsyntax#}. Upon completion of the async function, - execution would continue at the most recent {#syntax#}async{#endsyntax#} callsite or {#syntax#}resume{#endsyntax#} callsite, - and the return value of the async function would be lost. -
- {#code_begin|test|async_await#} - {#backend_stage1#} -const std = @import("std"); -const expect = std.testing.expect; - -test "async and await" { - // The test block is not async and so cannot have a suspend - // point in it. By using the nosuspend keyword, we promise that - // the code in amain will finish executing without suspending - // back to the test block. - nosuspend amain(); -} - -fn amain() void { - var frame = async func(); - comptime try expect(@TypeOf(frame) == @Frame(func)); - - const ptr: anyframe->void = &frame; - const any_ptr: anyframe = ptr; - - resume any_ptr; - await ptr; -} - -fn func() void { - suspend {} -} - {#code_end#} -- The {#syntax#}await{#endsyntax#} keyword is used to coordinate with an async function's - {#syntax#}return{#endsyntax#} statement. -
-- {#syntax#}await{#endsyntax#} is a suspend point, and takes as an operand anything that - coerces to {#syntax#}anyframe->T{#endsyntax#}. Calling {#syntax#}await{#endsyntax#} on - the frame of an async function will cause execution to continue at the - {#syntax#}await{#endsyntax#} callsite once the target function completes. -
-- There is a common misconception that {#syntax#}await{#endsyntax#} resumes the target function. - It is the other way around: it suspends until the target function completes. - In the event that the target function has already completed, {#syntax#}await{#endsyntax#} - does not suspend; instead it copies the - return value directly from the target function's frame. -
- {#code_begin|test|async_await_sequence#} - {#backend_stage1#} -const std = @import("std"); -const expect = std.testing.expect; - -var the_frame: anyframe = undefined; -var final_result: i32 = 0; - -test "async function await" { - seq('a'); - _ = async amain(); - seq('f'); - resume the_frame; - seq('i'); - try expect(final_result == 1234); - try expect(std.mem.eql(u8, &seq_points, "abcdefghi")); -} -fn amain() void { - seq('b'); - var f = async another(); - seq('e'); - final_result = await f; - seq('h'); -} -fn another() i32 { - seq('c'); - suspend { - seq('d'); - the_frame = @frame(); - } - seq('g'); - return 1234; -} - -var seq_points = [_]u8{0} ** "abcdefghi".len; -var seq_index: usize = 0; - -fn seq(c: u8) void { - seq_points[seq_index] = c; - seq_index += 1; -} - {#code_end#} -- In general, {#syntax#}suspend{#endsyntax#} is lower level than {#syntax#}await{#endsyntax#}. Most application - code will use only {#syntax#}async{#endsyntax#} and {#syntax#}await{#endsyntax#}, but event loop - implementations will make use of {#syntax#}suspend{#endsyntax#} internally. -
- {#header_close#} - - {#header_open|Async Function Example#} -- Putting all of this together, here is an example of typical - {#syntax#}async{#endsyntax#}/{#syntax#}await{#endsyntax#} usage: -
- {#code_begin|exe|async#} - {#backend_stage1#} -const std = @import("std"); -const Allocator = std.mem.Allocator; - -pub fn main() void { - _ = async amainWrap(); - - // Typically we would use an event loop to manage resuming async functions, - // but in this example we hard code what the event loop would do, - // to make things deterministic. - resume global_file_frame; - resume global_download_frame; -} - -fn amainWrap() void { - amain() catch |e| { - std.debug.print("{}\n", .{e}); - if (@errorReturnTrace()) |trace| { - std.debug.dumpStackTrace(trace.*); - } - std.process.exit(1); - }; -} - -fn amain() !void { - const allocator = std.heap.page_allocator; - var download_frame = async fetchUrl(allocator, "https://example.com/"); - var awaited_download_frame = false; - errdefer if (!awaited_download_frame) { - if (await download_frame) |r| allocator.free(r) else |_| {} - }; - - var file_frame = async readFile(allocator, "something.txt"); - var awaited_file_frame = false; - errdefer if (!awaited_file_frame) { - if (await file_frame) |r| allocator.free(r) else |_| {} - }; - - awaited_file_frame = true; - const file_text = try await file_frame; - defer allocator.free(file_text); - - awaited_download_frame = true; - const download_text = try await download_frame; - defer allocator.free(download_text); - - std.debug.print("download_text: {s}\n", .{download_text}); - std.debug.print("file_text: {s}\n", .{file_text}); -} - -var global_download_frame: anyframe = undefined; -fn fetchUrl(allocator: Allocator, url: []const u8) ![]u8 { - _ = url; // this is just an example, we don't actually do it! - const result = try allocator.dupe(u8, "this is the downloaded url contents"); - errdefer allocator.free(result); - suspend { - global_download_frame = @frame(); - } - std.debug.print("fetchUrl returning\n", .{}); - return result; -} - -var global_file_frame: anyframe = undefined; -fn readFile(allocator: Allocator, filename: []const u8) ![]u8 { - _ = filename; // this is just an example, we don't actually do it! - const result = try allocator.dupe(u8, "this is the file contents"); - errdefer allocator.free(result); - suspend { - global_file_frame = @frame(); - } - std.debug.print("readFile returning\n", .{}); - return result; -} - {#code_end#} -- Now we remove the {#syntax#}suspend{#endsyntax#} and {#syntax#}resume{#endsyntax#} code, and - observe the same behavior, with one tiny difference: -
- {#code_begin|exe|blocking#} - {#backend_stage1#} -const std = @import("std"); -const Allocator = std.mem.Allocator; - -pub fn main() void { - _ = async amainWrap(); -} - -fn amainWrap() void { - amain() catch |e| { - std.debug.print("{}\n", .{e}); - if (@errorReturnTrace()) |trace| { - std.debug.dumpStackTrace(trace.*); - } - std.process.exit(1); - }; -} - -fn amain() !void { - const allocator = std.heap.page_allocator; - var download_frame = async fetchUrl(allocator, "https://example.com/"); - var awaited_download_frame = false; - errdefer if (!awaited_download_frame) { - if (await download_frame) |r| allocator.free(r) else |_| {} - }; - - var file_frame = async readFile(allocator, "something.txt"); - var awaited_file_frame = false; - errdefer if (!awaited_file_frame) { - if (await file_frame) |r| allocator.free(r) else |_| {} - }; - - awaited_file_frame = true; - const file_text = try await file_frame; - defer allocator.free(file_text); - - awaited_download_frame = true; - const download_text = try await download_frame; - defer allocator.free(download_text); - - std.debug.print("download_text: {s}\n", .{download_text}); - std.debug.print("file_text: {s}\n", .{file_text}); -} - -fn fetchUrl(allocator: Allocator, url: []const u8) ![]u8 { - _ = url; // this is just an example, we don't actually do it! - const result = try allocator.dupe(u8, "this is the downloaded url contents"); - errdefer allocator.free(result); - std.debug.print("fetchUrl returning\n", .{}); - return result; -} - -fn readFile(allocator: Allocator, filename: []const u8) ![]u8 { - _ = filename; // this is just an example, we don't actually do it! - const result = try allocator.dupe(u8, "this is the file contents"); - errdefer allocator.free(result); - std.debug.print("readFile returning\n", .{}); - return result; -} - {#code_end#} -- Previously, the {#syntax#}fetchUrl{#endsyntax#} and {#syntax#}readFile{#endsyntax#} functions suspended, - and were resumed in an order determined by the {#syntax#}main{#endsyntax#} function. Now, - since there are no suspend points, the order of the printed "... returning" messages - is determined by the order of {#syntax#}async{#endsyntax#} callsites. -
- {#header_close#} - - {#header_close#} - {#header_open|Builtin Functions|2col#} + {#header_open|Builtin Functions|2col#}
Builtin functions are provided by the compiler and are prefixed with @.
The {#syntax#}comptime{#endsyntax#} keyword on a parameter means that the parameter must be known
@@ -8028,49 +7628,6 @@ comptime {
{#syntax#}@asyncCall(frame_buffer: []align(@alignOf(@Frame(anyAsyncFunction))) u8, result_ptr, function_ptr, args: anytype) anyframe->T{#endsyntax#}
- - {#syntax#}@asyncCall{#endsyntax#} performs an {#syntax#}async{#endsyntax#} call on a function pointer, - which may or may not be an {#link|async function|Async Functions#}. -
-- The provided {#syntax#}frame_buffer{#endsyntax#} must be large enough to fit the entire function frame. - This size can be determined with {#link|@frameSize#}. To provide a too-small buffer - invokes safety-checked {#link|Undefined Behavior#}. -
-- {#syntax#}result_ptr{#endsyntax#} is optional ({#link|null#} may be provided). If provided, - the function call will write its result directly to the result pointer, which will be available to - read after {#link|await|Async and Await#} completes. Any result location provided to - {#syntax#}await{#endsyntax#} will copy the result from {#syntax#}result_ptr{#endsyntax#}. -
- {#code_begin|test|async_struct_field_fn_pointer#} - {#backend_stage1#} -const std = @import("std"); -const expect = std.testing.expect; - -test "async fn pointer in a struct field" { - var data: i32 = 1; - const Foo = struct { - bar: fn (*i32) callconv(.Async) void, - }; - var foo = Foo{ .bar = func }; - var bytes: [64]u8 align(@alignOf(@Frame(func))) = undefined; - const f = @asyncCall(&bytes, {}, foo.bar, .{&data}); - try expect(data == 2); - resume f; - try expect(data == 4); -} - -fn func(y: *i32) void { - defer y.* += 2; - y.* += 1; - suspend {} -} - {#code_end#} - {#header_close#} - {#header_open|@atomicLoad#}{#syntax#}@atomicLoad(comptime T: type, ptr: *const T, comptime ordering: builtin.AtomicOrder) T{#endsyntax#}
@@ -8786,45 +8343,6 @@ test "decl access by string" { {#see_also|@intToFloat#} {#header_close#} - {#header_open|@frame#} -
{#syntax#}@frame() *@Frame(func){#endsyntax#}
- - This function returns a pointer to the frame for a given function. This type - can be {#link|coerced|Type Coercion#} to {#syntax#}anyframe->T{#endsyntax#} and - to {#syntax#}anyframe{#endsyntax#}, where {#syntax#}T{#endsyntax#} is the return type - of the function in scope. -
-- This function does not mark a suspension point, but it does cause the function in scope - to become an {#link|async function|Async Functions#}. -
- {#header_close#} - - {#header_open|@Frame#} -{#syntax#}@Frame(func: anytype) type{#endsyntax#}
- - This function returns the frame type of a function. This works for {#link|Async Functions#} - as well as any function without a specific calling convention. -
-- This type is suitable to be used as the return type of {#link|async|Async and Await#} which - allows one to, for example, heap-allocate an async function frame: -
- {#code_begin|test|heap_allocated_frame#} - {#backend_stage1#} -const std = @import("std"); - -test "heap allocated frame" { - const frame = try std.heap.page_allocator.create(@Frame(func)); - frame.* = async func(); -} - -fn func() void { - suspend {} -} - {#code_end#} - {#header_close#} - {#header_open|@frameAddress#}{#syntax#}@frameAddress() usize{#endsyntax#}
@@ -8840,17 +8358,6 @@ fn func() void {
{#header_close#} - {#header_open|@frameSize#} -{#syntax#}@frameSize(func: anytype) usize{#endsyntax#}
- - This is the same as {#syntax#}@sizeOf(@Frame(func)){#endsyntax#}, where {#syntax#}func{#endsyntax#} - may be runtime-known. -
-- This function is typically used in conjunction with {#link|@asyncCall#}. -
- {#header_close#} - {#header_open|@hasDecl#}{#syntax#}@hasDecl(comptime Container: type, comptime name: []const u8) bool{#endsyntax#}
@@ -9851,7 +9358,6 @@ test "integer truncation" {
At compile-time:
{#code_begin|test_err|operation caused overflow#} - {#backend_stage1#} comptime { const x = @shlExact(@as(u8, 0b01010101), 2); _ = x; @@ -10262,7 +9767,6 @@ pub fn main() void { {#header_open|Exact Right Shift Overflow#}At compile-time:
{#code_begin|test_err|exact shift shifted out 1 bits#} - {#backend_stage1#} comptime { const x = @shrExact(@as(u8, 0b10101010), 2); _ = x; @@ -10325,8 +9829,7 @@ pub fn main() void { {#header_close#} {#header_open|Exact Division Remainder#}At compile-time:
- {#code_begin|test_err|exact division had a remainder#} - {#backend_stage1#} + {#code_begin|test_err|exact division produced remainder#} comptime { const a: u32 = 10; const b: u32 = 3; @@ -10636,7 +10139,6 @@ fn bar(f: *Foo) void {At compile-time:
{#code_begin|test_err|null pointer casted to type#} - {#backend_stage1#} comptime { const opt_ptr: ?*i32 = null; const ptr = @ptrCast(*i32, opt_ptr); @@ -12271,9 +11773,6 @@ fn readU32Be() u32 {}