1 # Permission is granted to copy, distribute and/or modify this document
2 # under the terms of the GNU Free Documentation License, Version 1.3
3 # or any later version published by the Free Software Foundation;
4 # with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
5 # A copy of the license is included in the section entitled ``GNU
6 # Free Documentation License''.
8 # A copy of the license is also available from the Free Software
9 # Foundation Web site at http://www.gnu.org/licenses/fdl.html
11 # Altenately, this document is also available under the Lesser General
12 # Public License, version 3 or later, as published by the Free Software
15 # A copy of the license is also available from the Free Software
16 # Foundation Web site at http://www.gnu.org/licenses/lgpl.html
20 Welcome to 8sync's documentation!
21 8sync is an asynchronous programming environment for GNU Guile.
22 (Get it? 8sync? Async??? Quiet your groans, it's a great name!)
24 8sync has some nice properties:
26 - 8sync uses the actor model as its fundamental concurrency
27 synchronization mechanism.
28 Since the actor model is a "shared nothing" asynchronous
29 environment, you don't need to worry about deadlocks or other
30 tricky problems common to other asynchronous models.
31 Actors are modular units of code and state which communicate
32 by sending messages to each other.
33 - If you've done enough asynchronous programming, you're probably
34 familiar with the dreaded term "callback hell".
35 Getting around callback hell usually involves a tradeoff of other,
36 still rather difficult to wrap your brain around programming
38 8sync uses some clever tricks involving "delimited continuations"
39 under the hood to make the code you write look familiar and
41 When you need to send a request to another actor and get some
42 information back from it without blocking, there's no need
43 to write a separate procedure... 8sync's scheduler will suspend
44 your procedure and wake it back up when a response is ready.
45 - Even nonblocking I/O code is straightforward to write.
46 Thanks to the "suspendable ports" code introduced in Guile 2.2,
47 writing asynchronous, nonblocking networked code looks mostly
48 like writing the same synchronous code.
49 8sync's scheduler handles suspending and resuming networked
50 code that would otherwise block.
51 - 8sync aims to be "batteries included".
52 Useful subsystems for IRC bots, HTTP servers, and so on are
53 included out of the box.
54 - 8sync prioritizes live hacking.
55 If using an editor like Emacs with a nice mode like Geiser,
56 an 8sync-using developer can change and fine-tune the behavior
57 of code /while it runs/.
58 This makes both debugging and development much more natural,
59 allowing the right designs to evolve under your fingertips.
60 A productive hacker is a happy hacker, after all!
62 In the future, 8sync will also provide the ability to spawn and
63 communicate with actors on different threads, processes, and machines,
64 with most code running the same as if actors were running in the same
65 execution environment.
67 But as a caution, 8sync is still very young.
68 The API is stabilizing, but not yet stable, and it is not yet well
71 But, consider this as much an opportunity as a warning.
72 8sync is in a state where there is much room for feedback and
76 And now, into the wild, beautiful frontier.
81 ** Intro to the tutorial
83 IRC! Internet Relay Chat!
84 The classic chat protocol of the Internet.
85 And it turns out, one of the best places to learn about networked
88 In the 1990s I remember stumbling into some funky IRC chat rooms and
89 being astounded that people there had what they called "bots" hanging
91 From then until now, I've always enjoyed encountering bots whose range
92 of functionality has spanned from saying absurd things, to taking
93 messages when their "owners" were offline, to reporting the weather,
94 to logging meetings for participants.
95 And it turns out, IRC bots are a great way to cut your teeth on
96 networked programming; since IRC is a fairly simple line-delineated
97 protocol, it's a great way to learn to interact with sockets.
98 (My first IRC bot helped my team pick a place to go to lunch, previously
99 a source of significant dispute!)
100 At the time of writing, venture capital awash startups are trying to
101 turn chatbots into "big business"... a strange (and perhaps absurd)
102 thing given chat bots being a fairly mundane novelty amongst hackers
103 and teenagers everywhere in the 1990s.
105 We ourselves are going to explore chat bots as a basis for getting our
107 We'll start from a minimalist example using an irc bot with most of
108 the work done for us, then move on to constructing our own actors as
109 "game pieces" which interface with our bot, then experiment with just
110 how easy it is to add new networked layers by tacking on a high score
111 to our game, and as a finale we'll dive into writing our own little
112 irc bot framework "from scratch" on top of the 8sync actor model.
114 Alright, let's get going.
115 This should be a lot of fun!
117 ** A silly little IRC bot
121 ** Adding a "rankings" web page
123 ** Writing our own <irc-bot> from scratch