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.  If you've worked
  67 with most other asynchronous programming environments, you know that it
  68 generally isn't.  Usually asynchronous programming involves entering
  69 some sort of ``callback hell''.  Some nicer environments like Asyncio
  70 for Python provide generator-based coroutines, but even these require a
  71 lot of work to carefully line up.
  72
  73 Coding in 8sync, on the other hand, looks almost entirely like coding
  74 anywhere else.  This is because 8sync makes great use of a cool feature
  75 in Guile called ``delimited continuations'' to power natural-feeling
  76 coroutines.  Because of this, you can invoke your asynchronous code with
  77 a small wrapper around it, and that code will pop off to complete
  78 whatever other task it needs to do, and resume your function when it's
  79 ready passing back the appropriate value.  (No need to manually chain
  80 the coroutines together, and no callback hell at all!)
  81
  82 Now that's pretty cool!
  83
  84 @node Acknowledgements
  85 @chapter Acknowledgements
  86
  87 8sync has a number of inspirations:
  88
  89 @itemize @bullet
  90 @item
  91 @uref{https://docs.python.org/3.5/library/asyncio.html, asyncio}
  92 for Python provides a nice asynchronous programming environment, and
  93 makes great use of generator-style coroutines.  It's a bit more
  94 difficult to work with than 8sync (or so thinks the author) because you
  95 have to ``line up'' the coroutines.
  96
  97 @item
  98 @uref{http://dthompson.us/pages/software/sly.html, Sly}
  99 by David Thompson is an awesome functional reactive game programming
 100 library for Guile.  If you want to write graphical games, Sly is almost
 101 certainly a better choice than 8sync.  Thanks to David for being very
 102 patient in explaining tough concepts; experience on hacking Sly greatly
 103 informed 8sync's development.  (Check out Sly, it rocks!)
 104
 105 @item
 106 Reading @uref{https://mitpress.mit.edu/sicp/, SICP}, particularly
 107 @uref{https://mitpress.mit.edu/sicp/full-text/book/book-Z-H-19.html#%_chap_3,
 108       Chapter 3's writings on concurrent systems},
 109 greatly informed 8sync's design.
 110
 111 @item
 112 Finally, @uref{https://docs.python.org/3.5/library/asyncio.html, XUDD}
 113 was an earlier ``research project'' that preceeded 8sync.  It attempted
 114 to bring an actor model system to Python.  However, the author
 115 eventually grew frustrated with some of Python's limitations, fell in
 116 love with Guile, and well... now we have 8sync, which is much more
 117 general anyway.
 118
 119 @end itemize
 120
 121 The motivation to build 8sync came out of
 122 @uref{https://lists.gnu.org/archive/html/guile-devel/2015-10/msg00015.html, a conversation}
 123 at the FSF 30th party between Mark Weaver, David Thompson, Andrew
 124 Engelbrecht, and Christopher Allan Webber over how to build
 125 an asynchronous event loop for Guile and just what would be needed.
 126
 127 A little over a month after that, hacking on 8sync began!
 128
 129
 130 @node 8sync's license and general comments on copyleft
 131 @chapter 8sync's license and general comments on copyleft
 132
 133 8sync is released under the GNU LGPL (Lesser General Public License),
 134 version 3 or later, as published by the Free Software Foundation.  The
 135 short version of this is that if you distribute a modifications to
 136 8sync, whether alone or in some larger combination, must release the
 137 corresponding source code.  In general, it is best to contribute them
 138 back to 8sync under the same terms; we'd appreciate any enhancements or
 139 fixes to be contributed upstream to 8sync itself.  (This is an
 140 intentional oversimplification for brevity, please read the LGPL for the
 141 precise terms.)
 142
 143 This usage of the LGPL helps us ensure that 8sync and derivatives of
 144 8sync as a library will remain free.  However, we cannot provide the
 145 same freedom-protecting requirements for applications built on top of
 146 8sync.  Though it is not a requirement, we request you use 8sync to
 147 build free software rather than use it to contribute to the growing
 148 world of proprietary software.
 149
 150 The choice of the LGPL for 8sync was a strategic one, though in general,
 151 we encourage stronger copyleft.  (For more thinking on this position, see
 152 @uref{https://www.gnu.org/licenses/why-not-lgpl.html,
 153   Why you shouldn't use the Lesser GPL for your next library}.)
 154
 155 In particular, if you are building a library or application that uses
 156 8sync in some useful way, consider releasing your program under the GNU
 157 GPL or GNU AGPL!  In a world where more and more software is locked
 158 down, where software is used to restrict users, we could use every
 159 chance we can get to provide protections so that software which is free
 160 remains free, and encourages even more software freedom to be built upon
 161 it.
 162
 163 So to answer the question, ``Can I build a proprietary program on top of
 164 8sync?'' our response is ``Yes, but please don't.  Choose to release
 165 your software under a freedom-respecting license.  And help us turn the
 166 tide towards greater software freedom... consider a strong copyleft
 167 license!''
 168
 169
 170 @node Copying This Manual
 171 @appendix Copying This Manual
 172
 173 This manual is licensed under the GNU Free Documentation License, with
 174 no invariant sections.  At your option, it is also available under the
 175 GNU Lesser General Public License, as published by the Free Software
 176 Foundation, version 3 or any later version.
 177
 178 @menu
 179 * GNU Free Documentation License::  License for copying this manual.
 180 @end menu
 181
 182 @c Get fdl.texi from http://www.gnu.org/licenses/fdl.html
 183 @node GNU Free Documentation License
 184 @section GNU Free Documentation License
 185 @include fdl.texi
 186
 187 @node Index
 188 @unnumbered Index
 189
 190 @syncodeindex tp fn
 191 @syncodeindex vr fn
 192 @printindex fn
 193
 194 @bye
 195
 196 @c 8sync.texi ends here