diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/api.texi | 96 |
1 files changed, 47 insertions, 49 deletions
diff --git a/doc/api.texi b/doc/api.texi index 32a797b..1f69059 100644 --- a/doc/api.texi +++ b/doc/api.texi @@ -1134,16 +1134,16 @@ enemy follow and attack the player, or move an NPC back and forth in front of the item shop, or do both at the same time, a scripting system is a necessity. Chickadee comes with an asynchronous programming system in the @code{(chickadee scripting)} module. -Lightweight, cooperative threads known as ``coroutines'' allow the +Lightweight, cooperative threads known as ``scripts'' allow the programmer to write asynchronous code as if it were synchronous, and allow many such ``threads'' to run concurrently. -But before we dig deeper into coroutines, let's discuss the simple act +But before we dig deeper into scripts, let's discuss the simple act of scheduling tasks. @menu * Agendas:: Scheduling tasks. -* Coroutines:: Cooperative multitasking. +* Scripts:: Cooperative multitasking. * Tweening:: Animations. * Channels:: Publish data to listeners. @end menu @@ -1252,22 +1252,22 @@ Schedule @var{body} to be evaluated every @var{interval} amount of time. Repeat this @var{n} times, or indefinitely if not specified. @end deffn -@node Coroutines -@subsection Coroutines +@node Scripts +@subsection Scripts Now that we can schedule tasks, let's take things to the next level. It sure would be great if we could make procedures that described a series of actions that happened over time, especially if we could do so without contorting our code into a nest of callback procedures. -This is where coroutines come in. With coroutines we can write code -in a linear way, in a manner that appears to be synchronous, but with -the ability to suspend periodically in order to let other coroutines -have a turn and prevent blocking the game loop. Building on top of -the scheduling that agendas provide, here is a coroutine that models a -child trying to get their mother's attention: +This is where scripts come in. With scripts we can write code in a +linear way, in a manner that appears to be synchronous, but with the +ability to suspend periodically in order to let other scripts have a +turn and prevent blocking the game loop. Building on top of the +scheduling that agendas provide, here is a script that models a child +trying to get their mother's attention: @example -(coroutine +(script (while #t (display "mom!") (newline) @@ -1275,67 +1275,66 @@ child trying to get their mother's attention: @end example This code runs in an endless loop, but the @code{wait} procedure -suspends the coroutine and schedules it to be run later by the agenda. +suspends the script and schedules it to be run later by the agenda. So, after each iteration of the loop, control is returned back to the game loop and the program is not stuck spinning in a loop that will never exit. Pretty neat, eh? -Coroutines can suspend to any capable handler, not just the agenda. -The @code{yield} procedure will suspend the current coroutine and pass +Scripts can suspend to any capable handler, not just the agenda. +The @code{yield} procedure will suspend the current script and pass its ``continuation'' to a handler procedure. This handler procedure could do anything. Perhaps the handler stashes the continuation somewhere where it will be resumed when the user presses a specific key on the keyboard, or maybe it will be resumed when the player picks up an item off of the dungeon floor; the sky is the limit. -Sometimes it is necessary to abruptly terminate a coroutine after it -has been started. For example, when an enemy is defeated their AI -routine needs to be shut down. When a coroutine is spawned, a handle -to that coroutine is returned that can be used to cancel it when -desired. +Sometimes it is necessary to abruptly terminate a script after it has +been started. For example, when an enemy is defeated their AI routine +needs to be shut down. When a script is spawned, a handle to that +script is returned that can be used to cancel it when desired. @example -(define co (coroutine (while #t (display "hey\n") (wait 60)))) +(define script (script (while #t (display "hey\n") (wait 60)))) ;; sometime later -(cancel-coroutine co) +(cancel-script script) @end example -@deffn {Procedure} spawn-coroutine @var{thunk} -Apply @var{thunk} as a coroutine and return a handle to it. +@deffn {Procedure} spawn-script @var{thunk} +Apply @var{thunk} as a script and return a handle to it. @end deffn -@deffn {Syntax} coroutine @var{body} @dots{} -Evaluate @var{body} as a coroutine and return a handle to it. +@deffn {Syntax} script @var{body} @dots{} +Evaluate @var{body} as a script and return a handle to it. @end deffn -@deffn {Procedure} coroutine? @var{obj} -Return @code{#t} if @var{obj} is a coroutine handle. +@deffn {Procedure} script? @var{obj} +Return @code{#t} if @var{obj} is a script handle. @end deffn -@deffn {Procedure} coroutine-cancelled? @var{obj} +@deffn {Procedure} script-cancelled? @var{obj} Return @code{#t} if @var{obj} has been cancelled. @end deffn -@deffn {Procedure} coroutine-running? @var{obj} +@deffn {Procedure} script-running? @var{obj} Return @code{#t} if @var{obj} has not yet terminated or been cancelled. @end deffn -@deffn {Procedure} coroutine-complete? @var{obj} +@deffn {Procedure} script-complete? @var{obj} Return @code{#t} if @var{obj} has terminated. @end deffn -@deffn {Procedure} cancel-coroutine @var{co} -Prevent further execution of the coroutine @var{co}. +@deffn {Procedure} cancel-script @var{co} +Prevent further execution of the script @var{co}. @end deffn @deffn {Procedure} yield @var{handler} -Suspend the current coroutine and pass its continuation to the +Suspend the current script and pass its continuation to the procedure @var{handler}. @end deffn @deffn {Procedure} wait @var{duration} -Wait @var{duration} before resuming the current coroutine. +Wait @var{duration} before resuming the current script. @end deffn @deffn {Procedure} channel-get @var{channel} @@ -1352,11 +1351,11 @@ Evaluate @var{body} in an endless loop. Tweening is the process of transitioning something from an initial state to a final state over a pre-determined period of time. In other words, tweening is a way to create animation. The @code{tween} -procedure can be used within any coroutine like so: +procedure can be used within any script like so: @example (define x 0) -(coroutine +(script ;; 0 to 100 in 60 ticks of the agenda. (tween 60 0 100 (lambda (y) (set! x y)))) @end example @@ -1369,8 +1368,8 @@ amount of time between each update of the animation. To control how the animation goes from the initial to final state, an ``easing'' procedure may be specified. By default, the @code{smoothstep} easing is used, which is a more pleasing default -than a simplistic linear function. @xref{Easings} for a complete -list of available easing procedures. +than a simplistic linear function. @xref{Easings} for a complete list +of available easing procedures. The @var{interpolate} procedure computes the values in between @var{start} and @var{end}. By default, linear interpolation (``lerp'' @@ -1380,23 +1379,22 @@ for short) is used. @node Channels @subsection Channels -Channels are a tool for communicating amongst different coroutines. -One coroutine can write a value to the channel and another can read -from it. Reading or writing to a channel suspends that coroutine -until there is someone on the other end of the line to complete the -transaction. +Channels are a tool for communicating amongst different scripts. One +script can write a value to the channel and another can read from it. +Reading or writing to a channel suspends that script until there is +someone on the other end of the line to complete the transaction. Here's a simplistic example: @example (define c (make-channel)) -(coroutine +(script (forever (let ((item (channel-get c))) (pk 'got item)))) -(coroutine +(script (channel-put c 'sword) (channel-put c 'shield) (channel-put c 'potion)) @@ -1411,11 +1409,11 @@ Return @code{#t} if @var{obj} is a channel. @end deffn @deffn {Procedure} channel-get @var{channel} -Retrieve a value from @var{channel}. The current coroutine suspends +Retrieve a value from @var{channel}. The current script suspends until a value is available. @end deffn @deffn {Procedure} channel-put @var{channel} @var{data} -Send @var{data} to @var{channel}. The current coroutine suspends -until another coroutine is available to retrieve the value. +Send @var{data} to @var{channel}. The current script suspends until +another script is available to retrieve the value. @end deffn |