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