From def951e12bbe151431612a7facac2fec278f5be8 Mon Sep 17 00:00:00 2001 From: sogaiu <983021772@users.noreply.github.com> Date: Sat, 3 Jun 2023 14:46:05 +0900 Subject: [PATCH 1/3] Tweak fiber index doc --- content/docs/fibers/index.mdz | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/content/docs/fibers/index.mdz b/content/docs/fibers/index.mdz index b54b0756..49710924 100644 --- a/content/docs/fibers/index.mdz +++ b/content/docs/fibers/index.mdz @@ -23,13 +23,14 @@ fiber yields or throws an error, control is returned to the calling fiber. The parent fiber must then check what kind of state the fiber is in to differentiate errors from return values from user-defined signals. -To create a fiber, user the @code[fiber/new] function. The fiber constructor -take one or two arguments. The first, necessary argument is the function that -the fiber will execute. This function must accept an arity of zero. The next -optional argument is a collection of flags checking what kinds of signals to -trap and return via @code[resume]. This is useful so the programmer does not -need to handle all different kinds of signals from a fiber. Any un-trapped -signals are simply propagated to the previous calling fiber. +To create a fiber, use the @code[fiber/new] function. The fiber +constructor takes one or two arguments. The first argument (required) +is the function that the fiber will execute. This function must accept +an arity of zero. The next argument (optional) is a collection of +flags checking what kinds of signals to trap and return via +@code[resume]. This is useful so the programmer does not need to +handle all of the different kinds of signals from a fiber. Any +untrapped signals are simply propagated to the previous calling fiber. @codeblock[janet](``` (def f (fiber/new (fn [] @@ -55,7 +56,7 @@ signals are simply propagated to the previous calling fiber. ## Using fibers to capture errors Besides being used as coroutines, fibers can be used to implement error handling -(ie: exceptions). +(i.e. exceptions). @codeblock[janet](``` (defn my-function-that-errors [] From a85788100df63d0daac8ff1982cf26b66fcb6687 Mon Sep 17 00:00:00 2001 From: sogaiu <983021772@users.noreply.github.com> Date: Sat, 3 Jun 2023 14:56:41 +0900 Subject: [PATCH 2/3] Tweak fiber dynamic bindings doc --- content/docs/fibers/dynamic_bindings.mdz | 31 ++++++++++++------------ 1 file changed, 16 insertions(+), 15 deletions(-) diff --git a/content/docs/fibers/dynamic_bindings.mdz b/content/docs/fibers/dynamic_bindings.mdz index 737af786..708d7d7b 100644 --- a/content/docs/fibers/dynamic_bindings.mdz +++ b/content/docs/fibers/dynamic_bindings.mdz @@ -5,7 +5,7 @@ There are situations where the programmer would like to thread a parameter through multiple function calls, without passing that argument to every function explicitly. This can make code more concise, easier to read, and easier to -extend. Dynamic bindings are a mechanism that provide this in a safe and easy to +extend. Dynamic bindings are a mechanism that provides this in a safe and easy to use way. This is in contrast to lexically-scoped bindings, which are usually superior to dynamically-scoped bindings in terms of clarity, composability, and performance. However, dynamic scoping can be used to great effect for implicit @@ -54,38 +54,39 @@ print function @code`pp`. (def curr-env (fiber/getenv (fiber/current))) # The dynamic bindings we want to use -(def my-env {:pretty-format "Inside myblock: %.20P"}) +(def my-env @{:pretty-format "Inside myblock: %.20P"}) # Set up a new fiber (def f (fiber/new myblock)) (fiber/setenv f (table/setproto my-env curr-env)) # Run the code -(pp [1 2 3]) # prints "[1 2 3]" -(resume f) # prints "Inside myblock: [1 2 3]" -(pp [1 2 3]) # prints "[1 2 3]" +(pp [1 2 3]) # prints "(1 2 3)" +(resume f) # prints "Inside myblock: (1 2 3)" +(pp [1 2 3]) # prints "(1 2 3)" ``` This is verbose so the core library provides a macro, @code`with-dyns`, that makes it much clearer in the common case. @codeblock[janet]``` -(pp [1 2 3]) # prints "[1 2 3]" -# prints "Inside with-dyns: [1 2 3]" +(pp [1 2 3]) # prints "(1 2 3)" +# prints "Inside with-dyns: (1 2 3)" (with-dyns [:pretty-format "Inside with-dyns: %.20P"] (pp [1 2 3])) -(pp [1 2 3]) # prints "[1 2 3]" +(pp [1 2 3]) # prints "(1 2 3)" ``` ## When to use dynamic bindings -Dynamic bindings should be used when you want to pass around an implicit, global -context, especially when you want to automatically reset the context if an error -is raised. Since a dynamic binding is tied to the current fiber, when a fiber -exits the context is automatically unset. This is much easier and often more -efficient than manually trying to detect errors and unset context. Consider the -following example code, written once with a global var and once with a dynamic -binding. +Dynamic bindings should be used when you want to pass around an +implicit, global context, especially when you want to automatically +reset the context if an error is raised. Since a dynamic binding is +tied to the current fiber, when a fiber exits the context is +automatically unset. This is much easier and often more efficient than +manually trying to detect errors and unset the context. Consider the +following example code, written once with a global var and once with a +dynamic binding. ### Using a global var From 4483903c6147f3206a4e65ad4aa53317bb7ba862 Mon Sep 17 00:00:00 2001 From: sogaiu <983021772@users.noreply.github.com> Date: Sat, 3 Jun 2023 15:00:27 +0900 Subject: [PATCH 3/3] Tweak fiber error handling doc --- content/docs/fibers/error_handling.mdz | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/content/docs/fibers/error_handling.mdz b/content/docs/fibers/error_handling.mdz index d3a063cd..df504025 100644 --- a/content/docs/fibers/error_handling.mdz +++ b/content/docs/fibers/error_handling.mdz @@ -44,11 +44,11 @@ its second clause. @codeblock[janet]``` (try - (do - (print "inside block...") - (error "oops") - (print "will never get here")) - ([err] (print "caught error: " err))) + (do + (print "inside block...") + (error "oops") + (print "will never get here")) + ([err] (print "caught error: " err))) ``` ### @code`protect`