revival of the async-io functions

build.zig

@@ -75,6 +75,8 @@ pub const Exercise = struct {
     /// Hint to the user, why this has been skipped
     skip_hint: ?[]const u8 = null,
 
+    timestamp: bool = false,
+
     /// Returns the name of the main file with .zig stripped.
     pub fn name(self: Exercise) []const u8 {
         return std.fs.path.stem(self.main_file);
@@ -435,11 +437,30 @@ const ZiglingStep = struct {
             result.stderr;
 
         // Validate the output.
+        var exercise_output = self.exercise.output;
+
+        // Insert timestamp for exercise 84
+        if (self.exercise.timestamp) {
+            var ts_buf: [20]u8 = undefined;
+            const timestamp = std.fmt.bufPrint(&ts_buf, "{}", .{std.Io.Timestamp.now(io, .real).toSeconds()}) catch unreachable;
+
+            var buf: [100]u8 = undefined;
+            const prefix_len = 14;
+            const placeholder_len = 11;
+            @memcpy(buf[0..prefix_len], exercise_output[0..prefix_len]);
+            @memcpy(buf[prefix_len..][0..timestamp.len], timestamp);
+            const suffix = exercise_output[prefix_len + placeholder_len ..];
+            const suffix_dest_start = prefix_len + timestamp.len;
+            @memcpy(buf[suffix_dest_start..][0..suffix.len], suffix);
+
+            const total_len = prefix_len + timestamp.len + suffix.len;
+            exercise_output = buf[0..total_len];
+        }
+
         // NOTE: exercise.output can never contain a CR character.
         // See https://ziglang.org/documentation/master/#Source-Encoding.
         const output = trimLines(b.allocator, raw_output) catch @panic("OOM");
-        const exercise_output = self.exercise.output;
+        if (!std.mem.eql(u8, output, exercise_output)) {
-        if (!std.mem.eql(u8, output, self.exercise.output)) {
             const red = red_bold_text;
             const reset = reset_text;
 
@@ -698,7 +719,7 @@ const exercises = [_]Exercise{
         \\most part, you'll be taking directions from the Zig
         \\compiler itself.)
         \\
-        ,
+        , // pay attention to the comma
     },
     .{
         .main_file = "002_std.zig",
@@ -730,7 +751,7 @@ const exercises = [_]Exercise{
         \\Ziggy played guitar
         \\Jamming good with Andrew Kelley
         \\And the Spiders from Mars
-        ,
+        , // pay attention to the comma
         .hint = "Please fix the lyrics!",
     },
     .{
@@ -867,7 +888,7 @@ const exercises = [_]Exercise{
         \\  <span style="color: #00ff00">Green</span>
         \\  <span style="color: #0000ff">Blue</span>
         \\</p>
-        ,
+        , // pay attention to the comma
         .hint = "I'm feeling blue about this.",
     },
     .{
@@ -879,7 +900,7 @@ const exercises = [_]Exercise{
         .output =
         \\Character 1 - G:20 H:100 XP:10
         \\Character 2 - G:10 H:100 XP:20
-        ,
+        , // pay attention to the comma
     },
     .{
         .main_file = "039_pointers.zig",
@@ -903,7 +924,7 @@ const exercises = [_]Exercise{
         .output =
         \\Wizard (G:10 H:100 XP:20)
         \\  Mentor: Wizard (G:10000 H:100 XP:2340)
-        ,
+        , // pay attention to the comma
     },
     .{
         .main_file = "044_quiz5.zig",
@@ -947,7 +968,7 @@ const exercises = [_]Exercise{
         .output =
         \\Hand1: A 4 K 8
         \\Hand2: 5 2 Q J
-        ,
+        , // pay attention to the comma
     },
     .{
         .main_file = "053_slices2.zig",
@@ -1043,7 +1064,10 @@ const exercises = [_]Exercise{
         .main_file = "073_comptime8.zig",
         .output = "My llama value is 25.",
     },
-    .{ .main_file = "074_comptime9.zig", .output = "My llama value is 2.", .skip = false, .skip_hint = "This is actually correct as it is. :-)" },
+    .{
+        .main_file = "074_comptime9.zig",
+        .output = "My llama value is 2.",
+    },
     .{
         .main_file = "075_quiz8.zig",
         .output = "Archer's Point--2->Bridge--1->Dogwood Grove--3->Cottage--2->East Pond--1->Fox Pond",
@@ -1078,7 +1102,7 @@ const exercises = [_]Exercise{
         .main_file = "082_anonymous_structs3.zig",
         .output =
         \\"0"(bool):true "1"(bool):false "2"(i32):42 "3"(f32):3.141592
-        ,
+        , // pay attention to the comma
         .hint = "This one is a challenge! But you have everything you need.",
     },
     .{
@@ -1090,16 +1114,15 @@ const exercises = [_]Exercise{
     // direct link: https://github.com/ziglang/zig/issues/6025
     .{
         .main_file = "084_async.zig",
-        .output = "foo() A",
+        .output = "Current time: <timestamp>s since epoch",
-        .hint = "Read the facts. Use the facts.",
+        .timestamp = true,
-        .skip = true,
+        // .hint = "Read the facts. Use the facts.",
-        .skip_hint = "async has not been implemented in the current compiler version.",
+        // .skip = true,
+        // .skip_hint = "async has not been implemented in the current compiler version.",
     },
     .{
         .main_file = "085_async2.zig",
-        .output = "Hello async!",
+        .output = "Computing... the answer is: 42",
-        .skip = true,
-        .skip_hint = "async has not been implemented in the current compiler version.",
     },
     .{
         .main_file = "086_async3.zig",
@@ -1145,7 +1168,7 @@ const exercises = [_]Exercise{
         \\Ant is alive.
         \\Bee visited 17 flowers.
         \\Grasshopper hopped 32 meters.
-        ,
+        , // pay attention to the comma
     },
     .{
         .main_file = "093_hello_c.zig",
@@ -1221,7 +1244,7 @@ const exercises = [_]Exercise{
         \\2. Bard (Gold: 11, XP: 17)
         \\3. Bard (Gold: 5, XP: 55)
         \\4. Warrior (Gold: 7392, XP: 21)
-        ,
+        , // pay attention to the comma
     },
     .{
         .main_file = "102_testing.zig",
@@ -1247,7 +1270,7 @@ const exercises = [_]Exercise{
         \\and
         \\despair
         \\This little poem has 15 words!
-        ,
+        , // pay attention to the comma
     },
     .{
         .main_file = "104_threading.zig",
@@ -1261,7 +1284,7 @@ const exercises = [_]Exercise{
         \\thread 1: finished.
         \\thread 3: finished.
         \\Zig is cool!
-        ,
+        , // pay attention to the comma
     },
     .{
         .main_file = "105_threading2.zig",
@@ -1276,7 +1299,7 @@ const exercises = [_]Exercise{
         .output =
         \\AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
         \\Successfully Read 18 bytes: It's zigling time!
-        ,
+        , // pay attention to the comma
     },
     .{
         .main_file = "108_labeled_switch.zig",
@@ -1287,7 +1310,7 @@ const exercises = [_]Exercise{
         .output =
         \\Max difference (old fn): 0.014
         \\Max difference (new fn): 0.014
-        ,
+        , // pay attention to the comma
     },
     .{ .main_file = "110_quiz9.zig", .output =
     \\Toggle pins with XOR on PORTB
@@ -1334,6 +1357,6 @@ const exercises = [_]Exercise{
         \\
         \\This is the end for now!
         \\We hope you had fun and were able to learn a lot, so visit us again when the next exercises are available.
-        ,
+        , // pay attention to the comma
     },
 };

exercises/084_async.zig

@@ -1,58 +1,48 @@
 //
-// Six Facts:
+// In previous versions of Zig, async/await used special keywords
+// like 'suspend', 'resume', and 'async' that operated on stackframes
+// directly. Those keywords no longer exist!
 //
-// 1. The memory space allocated to your program for the
+// Zig 0.16 replaced them with a unified I/O interface: std.Io.
-// invocation of a function and all of its data is called a
+// This interface uses a VTable pattern - a struct of function pointers -
-// "stack frame".
+// to abstract over different concurrency backends:
 //
-// 2. The 'return' keyword "pops" the current function
+//   * Threaded  - classic thread-pool based I/O
-// invocation's frame off of the stack (it is no longer needed)
+//   * Uring     - Linux io_uring
-// and returns control to the place where the function was
+//   * Kqueue    - BSD/macOS
-// called.
+//   * Dispatch  - macOS Grand Central Dispatch
 //
-//     fn foo() void {
+// The Io struct itself is tiny:
-//         return; // Pop the frame and return control
+//
+//     const Io = struct {
+//         userdata: ?*anyopaque,   // opaque state of the backend
+//         vtable: *const VTable,   // table of function pointers
+//     };
+//
+// Your code receives an Io value and calls methods on it.
+// The backend is chosen at initialization time - your code doesn't
+// need to know which one it is!
+//
+// In Zig 0.16, main() receives a std.process.Init struct to opt
+// into I/O and concurrency support:
+//
+//     pub fn main(init: std.process.Init) !void {
+//         const io = init.io;
+//         // ... use io ...
 //     }
 //
-// 3. Like 'return', the 'suspend' keyword returns control to the
+// Let's start simple. Fix the main function to extract the Io
-// place where the function was called BUT the function
+// interface from init, then use it to get the current time.
-// invocation's frame remains so that it can regain control again
-// at a later time. Functions which do this are "async"
-// functions.
 //
-//     fn fooThatSuspends() void {
+const std = @import("std");
-//         suspend {} // return control, but leave the frame alone
-//     }
-//
-// 4. To call any function in async context and get a reference
-// to its frame for later use, use the 'async' keyword:
-//
-//     var foo_frame = async fooThatSuspends();
-//
-// 5. If you call an async function without the 'async' keyword,
-// the function FROM WHICH you called the async function itself
-// becomes async! In this example, the bar() function is now
-// async because it calls fooThatSuspends(), which is async.
-//
-//     fn bar() void {
-//         fooThatSuspends();
-//     }
-//
-// 6. The main() function cannot be async!
-//
-// Given facts 3 and 4, how do we fix this program (broken by facts
-// 5 and 6)?
-//
-const print = @import("std").debug.print;
 
-pub fn main() void {
+pub fn main(init: std.process.Init) !void {
-    // Additional Hint: you can assign things to '_' when you
+    const io = init.???;
-    // don't intend to do anything with them.
-    foo();
-}
 
-fn foo() void {
+    // Get the current wall-clock time using the Io interface.
-    print("foo() A\n", .{});
+    // Hint: Timestamp.now() takes an Io and a Clock type (.real = wall clock).
-    suspend {}
+    const timestamp = std.Io.Timestamp.now(io, .real);
-    print("foo() B\n", .{});
+
+    // Print the timestamp in seconds since the Unix epoch.
+    std.debug.print("Current time: {}s since epoch\n", .{timestamp.toSeconds()});
 }

exercises/085_async2.zig

@@ -1,28 +1,48 @@
 //
-// So, 'suspend' returns control to the place from which it was
+// Now that we know how to get an Io value, let's use it for
-// called (the "call site"). How do we give control back to the
+// asynchronous execution!
-// suspended function?
 //
-// For that, we have a new keyword called 'resume' which takes an
+// io.async() launches a function and returns a Future. The result
-// async function invocation's frame and returns control to it.
+// won't necessarily be available until you call .await() on it:
 //
-//     fn fooThatSuspends() void {
+//     var future = io.async(someFunction, .{ arg1, arg2 });
-//         suspend {}
+//     // ... do other work here ...
-//     }
+//     const result = future.await(io);
 //
-//     var foo_frame = async fooThatSuspends();
+// The function *may* run immediately or on another thread -
-//     resume foo_frame;
+// your code doesn't need to care! That's the beauty of the
+// Io abstraction. (In the Threaded backend, if no thread is
+// available, the function runs synchronously right away and
+// .await() just returns the already-computed result.)
 //
-// See if you can make this program print "Hello async!".
+// io.async() returns a Future(T) where T is the return type
+// of the function you passed in. Future has two key methods:
 //
-const print = @import("std").debug.print;
+//     .await(io)  - block until the result is ready, return it
+//     .cancel(io) - request cancellation, then return the result
+//
+// Fix this program so that computeAnswer runs asynchronously
+// and its result is properly awaited.
+//
+const std = @import("std");
 
-pub fn main() void {
+pub fn main(init: std.process.Init) !void {
-    var foo_frame = async foo();
+    const io = init.io;
+
+    // Launch computeAnswer asynchronously.
+    // io.async() takes a function and a tuple of its arguments.
+    var future = io.async(computeAnswer, .{ 6, 7 });
+
+    // Meanwhile, print something to show we're not blocked.
+    std.debug.print("Computing... ", .{});
+
+    // Now collect the result. What method on Future gives us
+    // the value, blocking if it isn't ready yet?
+    const answer = future.???(io);
+
+    std.debug.print("The answer is: {}\n", .{answer});
 }
 
-fn foo() void {
+fn computeAnswer(a: u32, b: u32) u32 {
-    print("Hello ", .{});
+    return a * b;
-    suspend {}
-    print("async!\n", .{});
 }