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 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
  86 programming.
  87
  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
  90 around.
  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.
 104
 105 We ourselves are going to explore chat bots as a basis for getting our
 106 feet wet in 8sync.
 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.
 113
 114 Alright, let's get started.
 115 This should be a lot of fun!
 116
 117 ** A silly little IRC bot
 118
 119 First of all, we're going to need to import some modules.  Put this at
 120 the top of your file:
 121
 122 #+BEGIN_SRC scheme
 123   (use-modules (8sync)               ; 8sync's agenda and actors
 124                (8sync systems irc)   ; the irc bot subsystem
 125                (oop goops)           ; 8sync's actors use GOOPS
 126                (ice-9 format)        ; basic string formatting
 127                (ice-9 match))        ; pattern matching
 128 #+END_SRC
 129
 130 Now we need to add our bot.  Initially, it won't do much.
 131
 132 #+BEGIN_SRC scheme
 133   (define-class <my-irc-bot> (<irc-bot>))
 134
 135   (define-method (handle-line (irc-bot <my-irc-bot>) speaker channel
 136                               line emote?)
 137     (if emote?
 138         (format #t "~a emoted ~s in channel ~a\n"
 139                 speaker line channel)
 140         (format #t "~a said ~s in channel ~a\n"
 141                 speaker line channel)))
 142 #+END_SRC
 143
 144 We've just defined our own IRC bot!
 145 This is an 8sync actor.
 146 (8sync uses GOOPS to define actors.)
 147 We extended the handle-line generic method, so this is the code that
 148 will be called whenever the IRC bot "hears" anything.
 149 For now the code is pretty basic: it just outputs whatever it "hears"
 150 from a user in a channel to the current output port.
 151 Pretty boring!
 152 But it should help us make sure we have things working when we kick
 153 things off.
 154
 155 Speaking of, even though we've defined our actor, it's not running
 156 yet.  Time to fix that!
 157
 158 #+BEGIN_SRC scheme
 159 (define* (run-bot #:key (username "examplebot")
 160                   (server "irc.freenode.net")
 161                   (channels '("##botchat")))
 162   (define hive (make-hive))
 163   (define irc-bot
 164     (bootstrap-actor* hive <my-irc-bot> "irc-bot"
 165                       #:username username
 166                       #:server server
 167                       #:channels channels))
 168   (run-hive hive '()))
 169 #+END_SRC
 170
 171 Actors are connected to something called a "hive", which is a
 172 special kind of actor that runs all the other actors.
 173 Actors can spawn other actors, but before we start the hive we use
 174 this special "bootstrap-actor*" method.
 175 It takes the hive as its first argument, the actor class as the second
 176 argument, a decorative "cookie" as the third argument (this is
 177 optional, but it helps with debugging... you can skip it by setting it
 178 to #f if you prefer), and the rest are initialization arguments to the
 179 actor.  bootstrap-actor* passes back not the actor itself (we don't
 180 get access to that usually) but the *id* of the actor.
 181 (More on this later.)
 182 Finally we run the hive with run-hive and pass it a list of
 183 "bootstrapped" messages.
 184 Normally actors send messages to each other (and sometimes themselves),
 185 but we need to send a message or messages to start things or else
 186 nothing is going to happen.
 187
 188 We can run it like:
 189
 190 #+BEGIN_SRC scheme
 191 (run-bot #:username "some-bot-username") ; be creative!
 192 #+END_SRC
 193
 194 Assuming all the tubes on the internet are properly connected, you
 195 should be able to join the "##botchat" channel on irc.freenode.net and
 196 see your bot join as well.
 197 Now, as you probably guessed, you can't really /do/ much yet.
 198 If you talk to the bot, it'll send messages to the terminal informing
 199 you as such, but it's hardly a chat bot if it's not chatting yet.
 200
 201 So let's do the most boring (and annoying) thing possible.
 202 Let's get it to echo whatever we say back to us.
 203 Change handle-line to this:
 204
 205 #+BEGIN_SRC scheme
 206   (define-method (handle-line (irc-bot <my-irc-bot>) speaker channel
 207                               line emote?)
 208     (<- (actor-id irc-bot) 'send-line channel
 209         (format #f "Bawwwwk! ~a says: ~a" speaker line)))
 210 #+END_SRC
 211
 212 This will do exactly what it looks like: repeat back whatever anyone
 213 says like an obnoxious parrot.
 214 Give it a try, but don't keep it running for too long... this
 215 bot is so annoying it's likely to get banned from whatever channel
 216 you put it in.
 217
 218 This method handler does have the advantage of being simple though.
 219 It introduces a new concept simply... sending a message!
 220 Whenever you see "<-", you can think of that as saying "send this
 221 message".
 222 The arguments to "<-" are as follows: the actor sending the message,
 223 the id of the actor the message is being sent to, the "action" we
 224 want to invoke (a symbol), and the rest are arguments to the
 225 "action handler" which is in this case send-line (with itself takes
 226 two arguments: the channel our bot should send a message to, and
 227 the line we want it to spit out to the channel).
 228
 229 (Footnote: 8sync's name for sending a message, "<-", comes from older,
 230 early lisp object oriented systems which were, as it turned out,
 231 inspired by the actor model!
 232 Eventually message passing was dropped in favor of something called
 233 "generic functions" or "generic methods"
 234 (you may observe we made use of such a thing in extending
 235 handle-line).
 236 Many lispers believe that there is no need for message passing
 237 with generic methods and some advanced functional techniques,
 238 but in a concurrent environment message passing becomes useful
 239 again, especially when the communicating objects / actors are not
 240 in the same address space.)
 241
 242 Normally in the actor model, we don't have direct references to
 243 an actor, only an identifier.
 244 This is for two reasons: to quasi-enforce the "shared nothing"
 245 environment (actors absolutely control their own resources, and
 246 "all you can do is send a message" to request that they modify
 247 them) and because... well, you don't even know where that actor is!
 248 Actors can be anything, and anywhere.
 249 It's possible in 8sync to have an actor on a remote hive, which means
 250 the actor could be on a remote process or even remote machine, and
 251 in most cases message passing will look exactly the same.
 252 (There are some exceptions; it's possible for two actors on the same
 253 hive to "hand off" some special types of data that can't be serialized
 254 across processes or the network, eg a socket or a closure, perhaps even
 255 one with mutable state.
 256 This must be done with care, and the actors should be careful both
 257 to ensure that they are both local and that the actor handing things
 258 off no longer accesses that value to preserve the actor model.
 259 But this is an advanced topic, and we are getting ahead of ourselves.)
 260 We have to supply the id of the receiving actor, and usually we'd have
 261 only the identifier.
 262 But since in this case, since the actor we're sending this to is
 263 ourselves, we have to pass in our identifier, since the Hive won't
 264 deliver to anything other than an address.
 265
 266 Astute readers may observe, since this is a case where we are just
 267 referencing our own object, couldn't we just call "sending a line"
 268 as a method of our own object without all the message passing?
 269 Indeed, we do have such a method, so we /could/ rewrite handle-line
 270 like so:
 271
 272 #+BEGIN_SRC scheme
 273   (define-method (handle-line (irc-bot <my-irc-bot>) speaker channel
 274                               line emote?)
 275     (irc-bot-send-line irc-bot channel
 276                        (format #f "Bawwwwk! ~a says: ~a" speaker line)))
 277 #+END_SRC
 278
 279 ... but we want to get you comfortable and familiar with message
 280 passing, and we'll be making use of this same message passing shortly
 281 so that /other/ actors may participate in communicating with IRC
 282 through our IRC bot.
 283
 284 Anyway, our current message handler is simply too annoying.
 285 What would be much more interesting is if we could recognize
 286 when an actor could repeat messages /only/ when someone is speaking
 287 to it directly.
 288 Luckily this is an easy adjustment to make.
 289
 290 #+BEGIN_SRC scheme
 291   (define-method (handle-line (irc-bot <my-irc-bot>) speaker channel
 292                               line emote?)
 293     (define my-name (irc-bot-username irc-bot))
 294     (define (looks-like-me? str)
 295       (or (equal? str my-name)
 296           (equal? str (string-concatenate (list my-name ":")))))
 297     (when (looks-like-me?)
 298       (<- (actor-id irc-bot) 'send-line channel
 299           (format #f "Bawwwwk! ~a says: ~a" speaker line))))
 300 #+END_SRC
 301
 302 This is relatively straightforward, but it isn't very interesting.
 303 What we would really like to do is have our bot respond to individual
 304 "commands" like this:
 305
 306 #+BEGIN_SRC text
 307   <foo-user> examplebot: hi!
 308   <examplebot> Oh hi foo-user!
 309   <foo-user> examplebot: botsnack
 310   <examplebot> Yippie! *does a dance!*
 311   <foo-user> examplebot: echo I'm a very silly bot
 312   <examplebot> I'm a very silly bot
 313 #+END_SRC
 314
 315 Whee, that looks like fun!
 316 To implement it, we're going to pull out Guile's pattern matcher.
 317
 318 #+BEGIN_SRC scheme
 319   (define-method (handle-line (irc-bot <my-irc-bot>) speaker channel
 320                               line emote?)
 321     (define my-name (irc-bot-username irc-bot))
 322     (define (looks-like-me? str)
 323       (or (equal? str my-name)
 324           (equal? str (string-concatenate (list my-name ":")))))
 325     (match (string-split line #\space)
 326       (((? looks-like-me? _) action action-args ...)
 327        (match action
 328          ;; The classic botsnack!
 329          ("botsnack"
 330           (<- (actor-id irc-bot) 'send-line channel
 331               "Yippie! *does a dance!*"))
 332          ;; Return greeting
 333          ((or "hello" "hello!" "hello." "greetings" "greetings." "greetings!"
 334               "hei" "hei." "hei!" "hi" "hi!")
 335           (<- (actor-id irc-bot) 'send-line channel
 336               (format #f "Oh hi ~a!" speaker)))
 337          ("echo"
 338           (<- (actor-id irc-bot) 'send-line channel
 339               (string-join action-args " ")))
 340
 341          ;; --->  Add yours here <---
 342
 343          ;; Default
 344          (_
 345           (<- (actor-id irc-bot) 'send-line channel
 346               "*stupid puppy look*"))))))
 347 #+END_SRC
 348
 349 Parsing the pattern matcher syntax is left as an exercise for the
 350 reader.
 351
 352 If you're getting the sense that we could make this a bit less wordy,
 353 you're right:
 354
 355 #+BEGIN_SRC scheme
 356   (define-method (handle-line (irc-bot <my-irc-bot>) speaker channel
 357                               line emote?)
 358     (define my-name (irc-bot-username irc-bot))
 359     (define (looks-like-me? str)
 360       (or (equal? str my-name)
 361           (equal? str (string-concatenate (list my-name ":")))))
 362     (define (respond respond-line)
 363       (<- (actor-id irc-bot) 'send-line channel
 364           respond-line))
 365     (match (string-split line #\space)
 366       (((? looks-like-me? _) action action-args ...)
 367        (match action
 368          ;; The classic botsnack!
 369          ("botsnack"
 370           (respond "Yippie! *does a dance!*"))
 371          ;; Return greeting
 372          ((or "hello" "hello!" "hello." "greetings" "greetings." "greetings!"
 373               "hei" "hei." "hei!" "hi" "hi." "hi!")
 374           (respond (format #f "Oh hi ~a!" speaker)))
 375          ("echo"
 376           (respond (string-join action-args " ")))
 377
 378          ;; --->  Add yours here <---
 379
 380          ;; Default
 381          (_
 382           (respond "*stupid puppy look*"))))))
 383 #+END_SRC
 384
 385 Okay, that looks pretty good!
 386 Now we have enough information to build an IRC bot that can do a lot
 387 of things.
 388 Take some time to experiment with extending the bot a bit before
 389 moving on to the next section!
 390 What cool commands can you add?
 391
 392 ** An intermission: about live hacking
 393
 394 This section is optional, but highly recommended.
 395 It requires that you're a user of GNU Emacs.
 396 If you aren't, don't worry... you can forge ahead and come back in case
 397 you ever do become an Emacs user.
 398 (If you're more familiar with Vi/Vim style editing, I hear good things
 399 about Spacemacs...)
 400
 401 So you may have noticed while updating the last section that the
 402 start/stop cycle of hacking isn't really ideal.
 403 You might either edit a file in your editor, then run it, or
 404 type the whole program into the REPL, but then you'll have to spend
 405 extra time copying it to a file.
 406 Wouldn't it be nice if it were possible to both write code in a
 407 file and try it as you go?
 408 And wouldn't it be even better if you could live edit a program
 409 while it's running?
 410
 411 Luckily, there's a great Emacs mode called Geiser which makes
 412 editing and hacking and experimenting all happen in harmony.
 413 And even better, 8sync is optimized for this experience.
 414 8sync provides easy drop-in "cooperative REPL" support, and
 415 most code can be simply redefined on the fly in 8sync through Geiser
 416 and actors will immediately update their behavior, so you can test
 417 and tweak things as you go.
 418
 419 Okay, enough talking.  Let's add it!
 420 Redefine run-bot like so:
 421
 422 #+BEGIN_SRC scheme
 423   (define* (run-bot #:key (username "examplebot")
 424                     (server "irc.freenode.net")
 425                     (channels '("##botchat"))
 426                     (repl-path "/tmp/8sync-repl"))
 427     (define hive (make-hive))
 428     (define irc-bot
 429       (bootstrap-actor* hive <my-irc-bot> "irc-bot"
 430                         #:username username
 431                         #:server server
 432                         #:channels channels))
 433     (define repl-manager
 434       (bootstrap-actor* hive <repl-manager> "repl"
 435                           #:path repl-path))
 436
 437     (run-hive hive '()))
 438 #+END_SRC
 439
 440 If we put a call to run-bot at the bottom of our file we can call it,
 441 and the repl-manager will start something we can connect to automatically.
 442 Horray!
 443 Now when we run this it'll start up a REPL with a unix domain socket at
 444 the repl-path.
 445 We can connect to it in emacs like so:
 446
 447 : M-x geiser-connect-local <RET> guile <RET> /tmp/8sync-repl <RET>
 448
 449 Okay, so what does this get us?
 450 Well, we can now live edit our program.
 451 Let's change how our bot behaves a bit.
 452 Let's change handle-line and tweak how the bot responds to a botsnack.
 453 Change this part:
 454
 455 #+BEGIN_SRC scheme
 456   ;; From this:
 457   ("botsnack"
 458    (respond "Yippie! *does a dance!*"))
 459
 460   ;; To this:
 461   ("botsnack"
 462    (respond "Yippie! *catches botsnack in midair!*"))
 463 #+END_SRC
 464
 465 Okay, now let's evaluate the change of the definition.
 466 You can hit "C-M-x" anywhere in the definition to re-evaluate.
 467 (You can also position your cursor at the end of the definition and press
 468 "C-x C-e", but I've come to like "C-M-x" better because I can evaluate as soon
 469 as I'm done writing.)
 470 Now, on IRC, ask your bot for a botsnack.
 471 The bot should give the new message... with no need to stop and start the
 472 program!
 473
 474 Let's fix a bug live.
 475 Our current program works great if you talk to your bot in the same
 476 IRC channel, but what if you try to talk to them over private message?
 477
 478 #+BEGIN_SRC text
 479 IRC> /query examplebot
 480 <foo-user> examplebot: hi!
 481 #+END_SRC
 482
 483 Hm, we aren't seeing any response on IRC!
 484 Huh?  What's going on?
 485 It's time to do some debugging.
 486 There are plenty of debugging tools in Guile, but sometimes the simplest
 487 is the nicest, and the simplest debugging route around is good old
 488 fashioned print debugging.
 489
 490 It turns out Guile has an under-advertised feature which makes print
 491 debugging really easy called "pk", pronounced "peek".
 492 What pk accepts a list of arguments, prints out the whole thing,
 493 but returns the last argument.
 494 This makes wrapping bits of our code pretty easy to see what's
 495 going on.
 496 So let's peek into our program with pk.
 497 Edit the respond section to see what channel it's really sending
 498 things to:
 499
 500 #+BEGIN_SRC scheme
 501   (define-method (handle-line (irc-bot <my-irc-bot>) speaker channel
 502                               line emote?)
 503     ;; [... snip ...]
 504     (define (respond respond-line)
 505       (<- (actor-id irc-bot) 'send-line (pk 'channel channel)
 506           respond-line))
 507     ;; [... snip ...]
 508     )
 509 #+END_SRC
 510
 511 Re-evaluate.
 512 Now let's ping our bot in both the channel and over PM.
 513
 514 #+BEGIN_SRC text
 515 ;;; (channel "##botchat")
 516
 517 ;;; (channel "sinkbot")
 518 #+END_SRC
 519
 520 Oh okay, this makes sense.
 521 When we're talking in a normal multi-user channel, the channel we see
 522 the message coming from is the same one we send to.
 523 But over PM, the channel is a username, and in this case the username
 524 we're sending our line of text to is ourselves.
 525 That isn't what we want.
 526 Let's edit our code so that if we see that the channel we're sending
 527 to looks like our own username that we respond back to the sender.
 528 (We can remove the pk now that we know what's going on.)
 529
 530 #+BEGIN_SRC scheme
 531   (define-method (handle-line (irc-bot <my-irc-bot>) speaker channel
 532                               line emote?)
 533     ;; [... snip ...]
 534     (define (respond respond-line)
 535       (<- (actor-id irc-bot) 'send-line
 536           (if (looks-like-me? channel)
 537               speaker    ; PM session
 538               channel)   ; normal IRC channel
 539           respond-line))
 540     ;; [... snip ...]
 541     )
 542 #+END_SRC
 543
 544 Re-evaluate and test.
 545
 546 #+BEGIN_SRC text
 547 IRC> /query examplebot
 548 <foo-user> examplebot: hi!
 549 <examplebot> Oh hi foo-user!
 550 #+END_SRC
 551
 552 Horray!
 553
 554 ** Writing our own actors
 555
 556 Let's write the most basic, boring actor possible.
 557 How about an actor that start sleeping, and keeps sleeping?
 558
 559 #+BEGIN_SRC scheme
 560   (use-modules (oop goops)
 561                (8sync))
 562
 563   (define-class <sleeper> (<actor>)
 564     (actions #:allocation #:each-subclass
 565              #:init-value (build-actions
 566                            (loop sleeper-loop))))
 567
 568   (define (sleeper-loop actor message)
 569     (while (actor-alive? actor)
 570       (display "Zzzzzzzz....\n")
 571       ;; Sleep for one second
 572       (8sleep 1)))
 573
 574   (let* ((hive (make-hive))
 575          (sleeper (bootstrap-actor hive <sleeper>)))
 576     (run-hive hive (list (bootstrap-message hive sleeper 'loop))))
 577 #+END_SRC
 578
 579 We see some particular things in this example.
 580 One thing is that our <sleeper> actor has an actions slot.
 581 This is used to look up what the "action handler" for a message is.
 582 We have to set the #:allocation to either #:each-subclass or #:class.
 583 (#:class should be fine, except there is [[https://debbugs.gnu.org/cgi/bugreport.cgi?bug=25211][a bug in Guile]] which keeps
 584 us from using it for now.)
 585
 586 In our sleeper-loop we also see a call to "8sleep".
 587 "8sleep" is like Guile's "sleep" method, except it is non-blocking
 588 and will always yield to the scheduler.
 589
 590 Our while loop also checks "actor-alive?" to see whether or not
 591 it is still registered.
 592 In general, if you keep a loop in your actor that regularly yields
 593 to the scheduler, you should check this.
 594 (An alternate way to handle it would be to not use a while loop at all
 595 but simply send a message to ourselves with "<-" to call the
 596 sleeper-loop handler again.
 597 If the actor was dead, the message simply would not be delivered and
 598 thus the loop would stop.)
 599
 600 This actor is pretty lazy though.
 601 Time to get back to work!
 602
 603 #+BEGIN_SRC scheme
 604   (use-modules (8sync)
 605                (oop goops))
 606
 607   (define-class <manager> (<actor>)
 608     (direct-report #:init-keyword #:direct-report
 609                    #:getter manager-direct-report)
 610     (actions #:allocation #:each-subclass
 611              #:init-value (build-actions
 612                            (assign-task manager-assign-task))))
 613
 614   (define (manager-assign-task manager message difficulty)
 615     "Delegate a task to our direct report"
 616     (display "manager> Work on this task for me!\n")
 617     (<- (manager-direct-report manager)
 618         'work-on-this difficulty))
 619 #+END_SRC
 620
 621 Here we're constructing a very simple manager actor.
 622 This manager keeps track of a direct report and tells them to start
 623 working on a task... simple delegation.
 624 Nothing here is really new, but note that our friend "<-" (which means
 625 "send message") is back.
 626 There's one difference this time... the first time we saw "<-" was in
 627 the handle-line procedure of the irc-bot, and in that case we explicitly
 628 pulled the actor-id after the actor we were sending the message to
 629 (ourselves), which we aren't doing here.
 630 But that was an unusual case, because the actor was ourself.
 631 In this case, and in general, actors don't have direct references to
 632 other actors; instead, all they have is access to identifiers which
 633 reference other actors.
 634
 635 #+BEGIN_SRC scheme
 636   (define-class <worker> (<actor>)
 637     (task-left #:init-keyword #:task-left
 638                #:accessor worker-task-left)
 639     (actions #:allocation #:each-subclass
 640              #:init-value (build-actions
 641                            (work-on-this worker-work-on-this))))
 642
 643   (define (worker-work-on-this worker message difficulty)
 644     "Work on one task until done."
 645     (set! (worker-task-left worker) difficulty)
 646     (display "worker> Whatever you say, boss!\n")
 647     (while (and (actor-alive? worker)
 648                 (> (worker-task-left worker) 0))
 649       (display "worker> *huff puff*\n")
 650       (set! (worker-task-left worker)
 651             (- (worker-task-left worker) 1))
 652       (8sleep (/ 1 3))))
 653 #+END_SRC
 654
 655 The worker also contains familiar code, but we now see that we can
 656 call 8sleep with non-integer real numbers.
 657
 658 Looks like there's nothing left to do but run it:
 659
 660 #+BEGIN_SRC scheme
 661   (let* ((hive (make-hive))
 662          (worker (bootstrap-actor hive <worker>))
 663          (manager (bootstrap-actor hive <manager>
 664                                    #:direct-report worker)))
 665     (run-hive hive (list (bootstrap-message hive manager 'assign-task 5))))
 666 #+END_SRC
 667
 668 #+BEGIN_SRC text
 669 manager> Work on this task for me!
 670 worker> Whatever you say, boss!
 671 worker> *huff puff*
 672 worker> *huff puff*
 673 worker> *huff puff*
 674 worker> *huff puff*
 675 worker> *huff puff*
 676 #+END_SRC
 677
 678 "<-" pays no attention to what happens with the messages it has sent
 679 off.
 680 This is useful in many cases... we can blast off many messages and
 681 continue along without holding anything back.
 682
 683 But sometimes we want to make sure that something completes before
 684 we do something else, or we want to send a message and get some sort
 685 of information back.
 686 Luckily 8sync comes with an answer to that with "<-wait", which will
 687 suspend the caller until the callee gives some sort of response, but
 688 which does not block the rest of the program from running.
 689 Let's try applying that to our own code by turning our manager
 690 into a micromanager.
 691
 692 #+END_SRC
 693 #+BEGIN_SRC scheme
 694   ;;; Update this method
 695   (define (manager-assign-task manager message difficulty)
 696     "Delegate a task to our direct report"
 697     (display "manager> Work on this task for me!\n")
 698     (<- (manager-direct-report manager)
 699         'work-on-this difficulty)
 700
 701     ;; Wait a moment, then call the micromanagement loop
 702     (8sleep (/ 1 2))
 703     (manager-micromanage-loop manager))
 704
 705   ;;; And add the following
 706   ;;;   (... Note: do not model actual employee management off this)
 707   (define (manager-micromanage-loop manager)
 708     "Pester direct report until they're done with their task."
 709     (display "manager> Are you done yet???\n")
 710     (let ((worker-is-done
 711            (mbody-val (<-wait (manager-direct-report manager)
 712                               'done-yet?))))
 713       (if worker-is-done
 714           (begin (display "manager> Oh!  I guess you can go home then.\n")
 715                  (<- (manager-direct-report manager) 'go-home))
 716           (begin (display "manager> Harumph!\n")
 717                  (8sleep (/ 1 2))
 718                  (when (actor-alive? manager)
 719                    (manager-micromanage-loop manager))))))
 720 #+END_SRC
 721
 722 We've appended a micromanagement loop here... but what's going on?
 723 "<-wait", as it sounds, waits for a reply, and returns a reply
 724 message.
 725 In this case there's a value in the body of the message we want,
 726 so we pull it out with mbody-val.
 727 (It's possible for a remote actor to return multiple values, in which
 728 case we'd want to use mbody-receive, but that's a bit more
 729 complicated.)
 730
 731 Of course, we need to update our worker accordingly as well.
 732
 733 #+BEGIN_SRC scheme
 734   ;;; Update the worker to add the following new actions:
 735   (define-class <worker> (<actor>)
 736     (task-left #:init-keyword #:task-left
 737                #:accessor worker-task-left)
 738     (actions #:allocation #:each-subclass
 739              #:init-value (build-actions
 740                            (work-on-this worker-work-on-this)
 741                            ;; Add these:
 742                            (done-yet? worker-done-yet?)
 743                            (go-home worker-go-home))))
 744
 745   ;;; New procedures:
 746   (define (worker-done-yet? worker message)
 747     "Reply with whether or not we're done yet."
 748     (let ((am-i-done? (= (worker-task-left worker) 0)))
 749       (if am-i-done?
 750           (display "worker> Yes, I finished up!\n")
 751           (display "worker> No... I'm still working on it...\n"))
 752       (<-reply message am-i-done?)))
 753
 754   (define (worker-go-home worker message)
 755     "It's off of work for us!"
 756     (display "worker> Whew!  Free at last.\n")
 757     (self-destruct worker))
 758 #+END_SRC
 759
 760 (As you've probably guessed, you wouldn't normally call =display=
 761 everywhere as we are in this program... that's just to make the
 762 examples more illustrative.)
 763
 764 Running it is the same as before:
 765
 766 #+BEGIN_SRC scheme
 767   (let* ((hive (make-hive))
 768          (worker (bootstrap-actor hive <worker>))
 769          (manager (bootstrap-actor hive <manager>
 770                                    #:direct-report worker)))
 771     (run-hive hive (list (bootstrap-message hive manager 'assign-task 5))))
 772 #+END_SRC
 773
 774 But the output is a bit different:
 775
 776 #+BEGIN_SRC scheme
 777 manager> Work on this task for me!
 778 worker> Whatever you say, boss!
 779 worker> *huff puff*
 780 worker> *huff puff*
 781 manager> Are you done yet???
 782 worker> No... I'm still working on it...
 783 manager> Harumph!
 784 worker> *huff puff*
 785 manager> Are you done yet???
 786 worker> *huff puff*
 787 worker> No... I'm still working on it...
 788 manager> Harumph!
 789 worker> *huff puff*
 790 manager> Are you done yet???
 791 worker> Yes, I finished up!
 792 manager> Oh!  I guess you can go home then.
 793 worker> Whew!  Free at last.
 794 #+END_SRC
 795
 796 "<-reply" is what actually returns the information to the actor
 797 waiting on the reply.
 798 It takes as an argument the actor sending the message, the message
 799 it is in reply to, and the rest of the arguments are the "body" of
 800 the message.
 801 (If an actor handles a message that is being "waited on" but does not
 802 explicitly reply to it, an auto-reply with an empty body will be
 803 triggered so that the waiting actor is not left waiting around.)
 804
 805 The last thing to note is the call to "self-destruct".
 806 This does what you might expect: it removes the actor from the hive.
 807 No new messages will be sent to it.
 808 Ka-poof!
 809
 810 ** Writing our own <irc-bot> from scratch
 811
 812 * API reference
 813
 814 * Systems reference
 815 ** IRC
 816 ** Web / HTTP
 817 ** COMMENT Websockets
 818
 819 * Addendum
 820 ** Recommended .emacs additions
 821
 822 In order for =mbody-receive= to indent properly, put this in your
 823 .emacs:
 824
 825 #+BEGIN_SRC emacs-lisp
 826 (put 'mbody-receive 'scheme-indent-function 2)
 827 #+END_SRC
 828
 829 ** 8sync and Fibers
 830
 831 One other major library for asynchronous communication in Guile-land
 832 is [[https://github.com/wingo/fibers/][Fibers]].
 833 There's a lot of overlap:
 834
 835  - Both use Guile's suspendable-ports facility
 836  - Both communicate between asynchronous processes using message passing;
 837    you don't have to squint hard to see the relationship between Fibers'
 838    channels and 8sync's actor inboxes.
 839
 840 However, there are clearly differences too.
 841 There's a one to one relationship between 8sync actors and an actor inbox,
 842 whereas each Fibers fiber may read from multiple channels, for example.
 843
 844 Luckily, it turns out there's a clear relationship, based on real,
 845 actual theory!
 846 8sync is based on the [[https://en.wikipedia.org/wiki/Actor_model][actor model]] whereas fibers follows
 847 [[http://usingcsp.com/][Communicating Sequential Processes (CSP)]], which is a form of
 848 [[https://en.wikipedia.org/wiki/Process_calculus][process calculi]].
 849 And it turns out, the
 850 [[https://en.wikipedia.org/wiki/Actor_model_and_process_calculi][relationship between the actor model and process calculi]] is well documented,
 851 and even more precisely, the
 852 [[https://en.wikipedia.org/wiki/Communicating_sequential_processes#Comparison_with_the_Actor_Model][relationship between CSP and the actor model]] is well understood too.
 853
 854 So, 8sync and Fibers do take somewhat different approaches, but both
 855 have a solid theoretical backing... and their theories are well
 856 understood in terms of each other.
 857 Good news for theory nerds!
 858
 859 (Since the actors and CSP are [[https://en.wikipedia.org/wiki/Dual_%28mathematics%29][dual]], maybe eventually 8sync will be
 860 implemented on top of Fibers... that remains to be seen!)
 861