doc: Add addendum section on relationship between 8sync and Fibers.
[8sync.git] / doc / 8sync-new-manual.org
index 1caa79b8ccb15adfa5e52c4c46c17b7a9ee5ddae..dd8ad505261fc725a2c257f0647b7546635d23b2 100644 (file)
@@ -205,7 +205,7 @@ Change handle-line to this:
 #+BEGIN_SRC scheme
   (define-method (handle-line (irc-bot <my-irc-bot>) speaker channel
                               line emote?)
-    (<- irc-bot (actor-id irc-bot) 'send-line channel
+    (<- (actor-id irc-bot) 'send-line channel
         (format #f "Bawwwwk! ~a says: ~a" speaker line)))
 #+END_SRC
 
@@ -295,7 +295,7 @@ Luckily this is an easy adjustment to make.
       (or (equal? str my-name)
           (equal? str (string-concatenate (list my-name ":")))))
     (when (looks-like-me?)
-      (<- irc-bot (actor-id irc-bot) 'send-line channel
+      (<- (actor-id irc-bot) 'send-line channel
           (format #f "Bawwwwk! ~a says: ~a" speaker line))))
 #+END_SRC
 
@@ -327,22 +327,22 @@ To implement it, we're going to pull out Guile's pattern matcher.
        (match action
          ;; The classic botsnack!
          ("botsnack"
-          (<- irc-bot (actor-id irc-bot) 'send-line channel
+          (<- (actor-id irc-bot) 'send-line channel
               "Yippie! *does a dance!*"))
          ;; Return greeting
          ((or "hello" "hello!" "hello." "greetings" "greetings." "greetings!"
               "hei" "hei." "hei!" "hi" "hi!")
-          (<- irc-bot (actor-id irc-bot) 'send-line channel
+          (<- (actor-id irc-bot) 'send-line channel
               (format #f "Oh hi ~a!" speaker)))
          ("echo"
-          (<- irc-bot (actor-id irc-bot) 'send-line channel
+          (<- (actor-id irc-bot) 'send-line channel
               (string-join action-args " ")))
 
          ;; --->  Add yours here <---
 
          ;; Default
          (_
-          (<- irc-bot (actor-id irc-bot) 'send-line channel
+          (<- (actor-id irc-bot) 'send-line channel
               "*stupid puppy look*"))))))
 #+END_SRC
 
@@ -360,7 +360,7 @@ you're right:
       (or (equal? str my-name)
           (equal? str (string-concatenate (list my-name ":")))))
     (define (respond respond-line)
-      (<- irc-bot (actor-id irc-bot) 'send-line channel
+      (<- (actor-id irc-bot) 'send-line channel
           respond-line))
     (match (string-split line #\space)
       (((? looks-like-me? _) action action-args ...)
@@ -503,7 +503,7 @@ things to:
                               line emote?)
     ;; [... snip ...]
     (define (respond respond-line)
-      (<- irc-bot (actor-id irc-bot) 'send-line (pk 'channel channel)
+      (<- (actor-id irc-bot) 'send-line (pk 'channel channel)
           respond-line))
     ;; [... snip ...]
     )
@@ -533,7 +533,7 @@ to looks like our own username that we respond back to the sender.
                               line emote?)
     ;; [... snip ...]
     (define (respond respond-line)
-      (<- irc-bot (actor-id irc-bot) 'send-line
+      (<- (actor-id irc-bot) 'send-line
           (if (looks-like-me? channel)
               speaker    ; PM session
               channel)   ; normal IRC channel
@@ -567,7 +567,7 @@ How about an actor that start sleeping, and keeps sleeping?
                            (loop sleeper-loop))))
 
   (define (sleeper-loop actor message)
-    (while (actor-am-i-alive? actor)
+    (while (actor-alive? actor)
       (display "Zzzzzzzz....\n")
       ;; Sleep for one second
       (8sleep 1)))
@@ -588,7 +588,7 @@ In our sleeper-loop we also see a call to "8sleep".
 "8sleep" is like Guile's "sleep" method, except it is non-blocking
 and will always yield to the scheduler.
 
-Our while loop also checks "actor-am-i-alive?" to see whether or not
+Our while loop also checks "actor-alive?" to see whether or not
 it is still registered.
 In general, if you keep a loop in your actor that regularly yields
 to the scheduler, you should check this.
@@ -615,7 +615,7 @@ Time to get back to work!
   (define (manager-assign-task manager message difficulty)
     "Delegate a task to our direct report"
     (display "manager> Work on this task for me!\n")
-    (<- manager (manager-direct-report manager)
+    (<- (manager-direct-report manager)
         'work-on-this difficulty))
 #+END_SRC
 
@@ -645,7 +645,7 @@ reference other actors.
     ""
     (set! (worker-task-left worker) difficulty)
     (display "worker> Whatever you say, boss!\n")
-    (while (and (actor-am-i-alive? worker)
+    (while (and (actor-alive? worker)
                 (> (worker-task-left worker) 0))
       (display "worker> *huff puff*\n")
       (set! (worker-task-left worker)
@@ -698,7 +698,7 @@ into a micromanager.
   (define (manager-assign-task manager message difficulty)
     "Delegate a task to our direct report"
     (display "manager> Work on this task for me!\n")
-    (<- manager (manager-direct-report manager)
+    (<- (manager-direct-report manager)
         'work-on-this difficulty)
 
     ;; call the micromanagement loop
@@ -710,15 +710,15 @@ into a micromanager.
     "Pester direct report until they're done with their task."
     (display "manager> Are you done yet???\n")
     (let ((still-working
-           (msg-val (<-wait manager (manager-direct-report manager)
+           (msg-val (<-wait (manager-direct-report manager)
                             'done-yet?))))
       (if still-working
           (begin (display "manager> Harumph!\n")
                  (8sleep 1)
-                 (when (actor-am-i-alive? manager)
+                 (when (actor-alive? manager)
                    (manager-micromanage-loop manager)))
           (begin (display "manager> Oh!  I guess you can go home then.\n")
-                 (<- manager (manager-direct-report manager) 'go-home)))))
+                 (<- (manager-direct-report manager) 'go-home)))))
 #+END_SRC
 
 We've appended a micromanagement loop here... but what's going on?
@@ -746,7 +746,7 @@ Of course, we need to update our worker accordingly as well.
   ;;; New procedures:
   (define (worker-done-yet? worker message)
     "Reply with whether or not we're done yet."
-    (<-reply worker message
+    (<-reply message
              (= (worker-task-left worker) 0)))
 
   (define (worker-go-home worker message)
@@ -777,3 +777,38 @@ Ka-poof!
 ** IRC
 ** Web / HTTP
 ** COMMENT Websockets
+
+* Addendum
+** 8sync and Fibers
+
+One other major library for asynchronous communication in Guile-land
+is [[https://github.com/wingo/fibers/][Fibers]].
+There's a lot of overlap:
+
+ - Both use Guile's suspendable-ports facility
+ - Both communicate between asynchronous processes using message passing;
+   you don't have to squint hard to see the relationship between Fibers'
+   channels and 8sync's actor inboxes.
+
+However, there are clearly differences too.
+There's a one to one relationship between 8sync actors and an actor inbox,
+whereas each Fibers fiber may read from multiple channels, for example.
+
+Luckily, it turns out there's a clear relationship, based on real,
+actual theory!
+8sync is based on the [[https://en.wikipedia.org/wiki/Actor_model][actor model]] whereas fibers follows
+[[http://usingcsp.com/][Communicating Sequential Processes (CSP)]], which is a form of
+[[https://en.wikipedia.org/wiki/Process_calculus][process calculi]]. 
+And it turns out, the
+[[https://en.wikipedia.org/wiki/Actor_model_and_process_calculi][relationship between the actor model and process calculi]] is well documented,
+and even more precisely, the
+[[https://en.wikipedia.org/wiki/Communicating_sequential_processes#Comparison_with_the_Actor_Model][relationship between CSP and the actor model]] is well understood too.
+
+So, 8sync and Fibers do take somewhat different approaches, but both
+have a solid theoretical backing... and their theories are well
+understood in terms of each other.
+Good news for theory nerds!
+
+(Since the actors and CSP are [[https://en.wikipedia.org/wiki/Dual_%28mathematics%29][dual]], maybe eventually 8sync will be
+implemented on top of Fibers... that remains to be seen!)
+