doc/8sync.texi

   1 \input texinfo   @c -*-texinfo-*-
   2 @c %**start of header
   3 @setfilename 8sync.info
   4 @settitle 8sync
   5 @c %**end of header
   6 @copying
   7 Copyright @copyright{} 2015  Christopher Allan Webber @email{cwebber@@dustycloud.org}
   8 @end copying
   9
  10 @quotation
  11 Permission is granted to copy, distribute and/or modify this document
  12 under the terms of the GNU Free Documentation License, Version 1.3
  13 or any later version published by the Free Software Foundation;
  14 with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
  15 A copy of the license is included in the section entitled ``GNU
  16 Free Documentation License''.
  17
  18 A copy of the license is also available from the Free Software
  19 Foundation Web site at @url{http://www.gnu.org/licenses/fdl.html}.
  20
  21 Altenately, this document is also available under the Lesser General
  22 Public License, version 3 or later, as published by the Free Software
  23 Foundation.
  24
  25 A copy of the license is also available from the Free Software
  26 Foundation Web site at @url{http://www.gnu.org/licenses/lgpl.html}.
  27
  28 @end quotation
  29
  30
  31 @titlepage
  32 @title 8sync 0.1
  33 @subtitle Using 8sync, an asynchronous event loop for Guile
  34 @author Christopher Allan Webber
  35 @page
  36 @vskip 0pt plus 1filll
  37 @insertcopying
  38 @end titlepage
  39
  40 @c Output the table of the contents at the beginning.
  41 @contents
  42
  43 @ifnottex
  44 @node Top
  45 @top 8sync
  46
  47 @insertcopying
  48 @end ifnottex
  49
  50 @c Generate the nodes for this menu with `C-c C-u C-m'.
  51
  52
  53 @c Update all node entries with `C-c C-u C-n'.
  54 @c Insert new nodes with `C-c C-c n'.
  55
  56 @menu
  57 * Introduction::
  58 * Acknowledgements::
  59 * Copying This Manual::
  60 * Index::
  61 @end menu
  62
  63 @node Introduction
  64 @chapter Introduction
  65
  66 8sync's goal is to make asynchronous programming easy.
  67 If you've worked with most other asynchronous programming environments,
  68   you know that it generally isn't.
  69 Usually asynchronous programming involves entering some sort of
  70   ``callback hell''.
  71 Some nicer environments like Asyncio for Python provide generator-based
  72   coroutines, but even these require a lot of work to carefully line up.
  73
  74 Coding in 8sync, on the other hand, looks almost entirely like coding
  75   anywhere else.
  76 This is because 8sync makes great use of a cool feature in Guile called
  77   ``delimited continuations'' to power natural-feeling coroutines.
  78 Because of this, you can invoke your asynchronous code with a small wrapper
  79   around it, and that code will pop off to complete whatever other task it
  80   needs to do, and resume your function when it's ready passing back the
  81   appropriate value.
  82 (No need to manually chain the coroutines together, and no callback hell at
  83   all!)
  84
  85 Now that's pretty cool!
  86
  87 @node Acknowledgements
  88 @chapter Acknowledgements
  89
  90 8sync has a number of inspirations:
  91
  92 @itemize @bullet
  93 @item
  94 @uref{https://docs.python.org/3.5/library/asyncio.html, asyncio}
  95   for Python provides a nice asynchronous programming environment, and
  96   makes great use of generator-style coroutines.
  97 It's a bit more difficult to work with than 8sync (or so thinks the author)
  98   because you have to ``line up'' the coroutines.
  99
 100 @item
 101 @uref{http://dthompson.us/pages/software/sly.html, Sly}
 102   by David Thompson is an awesome functional reactive game programming
 103   library for Guile.
 104 If you want to write graphical games, Sly is almost certainly a better choice
 105   than 8sync.
 106 Thanks to David for being very patient in explaining tough concepts;
 107   experience on hacking Sly greatly informed 8sync's development.
 108 (Check out Sly, it rocks!)
 109
 110 @item
 111 Reading @uref{https://mitpress.mit.edu/sicp/, SICP}, particularly
 112   @uref{https://mitpress.mit.edu/sicp/full-text/book/book-Z-H-19.html#%_chap_3,
 113         Chapter 3's writings on concurrent systems},
 114   greatly informed 8sync's design.
 115
 116 @item
 117 Finally, @uref{https://docs.python.org/3.5/library/asyncio.html, XUDD}
 118   was an earlier ``research project'' that preceeded 8sync.
 119 It attempted to bring an actor model system to Python.
 120 However, the author eventually grew frustrated with some of Python's
 121   limitations, fell in love with Guile, and well... now we have 8sync, which
 122   is much more general anyway.
 123
 124 @end itemize
 125
 126 The motivation to build 8sync came out of
 127   @uref{https://lists.gnu.org/archive/html/guile-devel/2015-10/msg00015.html,
 128         a conversation}
 129   at the FSF 30th party between Mark Weaver, David Thompson, Andrew
 130   Engelbrecht, and Christopher Allan Webber over how to build
 131   an asynchronous event loop for Guile and just what would be needed.
 132
 133 A little over a month after that, hacking on 8sync began!
 134
 135
 136 @node 8sync's license and general comments on copyleft
 137 @chapter 8sync's license and general comments on copyleft
 138
 139 8sync is released under the GNU LGPL (Lesser General Public License),
 140   version 3 or later, as published by the Free Software Foundation.
 141 The short version of this is that if you distribute a modifications to
 142   8sync, whether alone or in some larger combination, must release the
 143   corresponding source code.
 144 A program which uses this library, if distributed without source code,
 145   must also allow relinking with a modified version of this library.
 146 In general, it is best to contribute them back to 8sync under the same terms;
 147   we'd appreciate any enhancements or fixes to be contributed upstream to
 148   8sync itself.
 149 (This is an intentional oversimplification for brevity, please read the LGPL
 150   for the precise terms.)
 151
 152 This usage of the LGPL helps us ensure that 8sync and derivatives of
 153 8sync as a library will remain free.
 154 However, we cannot provide the same freedom-protecting requirements for
 155   applications built on top of 8sync.
 156 Though it is not a requirement, we request you use 8sync to build free
 157   software rather than use it to contribute to the growing world of
 158   proprietary software.
 159
 160 The choice of the LGPL for 8sync was a strategic one, though in general,
 161   we encourage stronger copyleft.
 162 (For more thinking on this position, see
 163   @uref{https://www.gnu.org/licenses/why-not-lgpl.html,
 164         Why you shouldn't use the Lesser GPL for your next library}.)
 165
 166 In particular, if you are building a library or application that uses
 167   8sync in some useful way, consider releasing your program under the GNU
 168   GPL or GNU AGPL!
 169 In a world where more and more software is locked down, where software is used
 170   to restrict users, we could use every chance we can get to provide
 171   protections so that software which is free remains free, and encourages even
 172   more software freedom to be built upon it.
 173
 174 So to answer the question, ``Can I build a proprietary program on top of
 175   8sync?'' our response is
 176   ``Yes, but please don't.
 177     Choose to release your software under a freedom-respecting license.
 178     And help us turn the tide towards greater software freedom...
 179       consider a strong copyleft license!''
 180
 181
 182 @node Copying This Manual
 183 @appendix Copying This Manual
 184
 185 This manual is licensed under the GNU Free Documentation License, with
 186 no invariant sections.  At your option, it is also available under the
 187 GNU Lesser General Public License, as published by the Free Software
 188 Foundation, version 3 or any later version.
 189
 190 @menu
 191 * GNU Free Documentation License::  License for copying this manual.
 192 @end menu
 193
 194 @c Get fdl.texi from http://www.gnu.org/licenses/fdl.html
 195 @node GNU Free Documentation License
 196 @section GNU Free Documentation License
 197 @include fdl.texi
 198
 199 @node Index
 200 @unnumbered Index
 201
 202 @syncodeindex tp fn
 203 @syncodeindex vr fn
 204 @printindex fn
 205
 206 @bye
 207
 208 @c 8sync.texi ends here