summaryrefslogtreecommitdiff
path: root/doc/api.texi
diff options
context:
space:
mode:
Diffstat (limited to 'doc/api.texi')
-rw-r--r--doc/api.texi96
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