doc/8sync-new-manual.org

   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''.
   7 #
   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
  10 #
  11 # Altenately, this document is also available under the Lesser General
  12 # Public License, version 3 or later, as published by the Free Software
  13 # Foundation.
  14 #
  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
  17
  18 * Preface
  19
  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!)
  23
  24 8sync has some nice properties:
  25
  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
  37    patterns.
  38    8sync uses some clever tricks involving "delimited continuations"
  39    under the hood to make the code you write look familiar and
  40    straightforward.
  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!
  61
  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.
  66
  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
  69 "battle-tested".
  70 Hacker beware!
  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
  73 contributions.
  74 Your help wanted!
  75
  76 And now, into the wild, beautiful frontier.
  77 Onward!
  78
  79 * Tutorial
  80
  81 ** Intro to the tutorial
  82
  83 ** A fun little IRC bot
  84
  85 ** Battle bot!
  86
  87 ** Adding a "rankings" web page
  88
  89 ** Writing our own <irc-bot> from scratch
  90
  91 * API reference
  92