X-Git-Url: https://jxself.org/git/?p=8sync.git;a=blobdiff_plain;f=doc%2F8sync.texi;h=933e32cd391b72cf586586de5eda5f0b6fc1dccb;hp=7ddc4aa3582777ae9ce96ceb96e512b5d7ee617c;hb=e6b478ce79bd4667d6f31554053134b11e39760c;hpb=f8919ceb386574e7f91545f2ab2d3063ca7c92a4 diff --git a/doc/8sync.texi b/doc/8sync.texi index 7ddc4aa..933e32c 100644 --- a/doc/8sync.texi +++ b/doc/8sync.texi @@ -4,7 +4,7 @@ @settitle 8sync @c %**end of header @copying -Copyright @copyright{} 2015 Christopher Allan Webber @email{cwebber@dustycloud.org} +Copyright @copyright{} 2015 Christopher Allan Webber @email{cwebber@@dustycloud.org} @end copying @quotation @@ -29,7 +29,7 @@ Foundation Web site at @url{http://www.gnu.org/licenses/lgpl.html}. @titlepage -@title 8sync 0.1 +@title 8sync @subtitle Using 8sync, an asynchronous event loop for Guile @author Christopher Allan Webber @page @@ -37,8 +37,6 @@ Foundation Web site at @url{http://www.gnu.org/licenses/lgpl.html}. @insertcopying @end titlepage -@end ifnottex - @c Output the table of the contents at the beginning. @contents @@ -52,24 +50,190 @@ Foundation Web site at @url{http://www.gnu.org/licenses/lgpl.html}. @c Generate the nodes for this menu with `C-c C-u C-m'. +@c Update all node entries with `C-c C-u C-n'. +@c Insert new nodes with `C-c C-c n'. + @menu -* Introduction:: About 8sync +* Introduction:: +* Acknowledgements:: +* 8sync's license and general comments on copyleft:: +* Installation:: +* Getting started:: +* API Reference:: +* Contributing:: * Copying This Manual:: -* Index:: Complete index. +* Index:: @end menu -@c Update all node entries with `C-c C-u C-n'. -@c Insert new nodes with `C-c C-c n'. + @node Introduction @chapter Introduction -8sync 8sync 8sync! - +8sync's goal is to make asynchronous programming easy. +If you've worked with most other asynchronous programming environments, +you know that it generally isn't. +Usually asynchronous programming involves entering some sort of +`callback hell''. +Some nicer environments like Asyncio for Python provide generator-based +coroutines, but even these require a lot of work to carefully line up. + +Coding in 8sync, on the other hand, looks almost entirely like coding +anywhere else. +This is because 8sync makes great use of a cool feature in Guile called +``delimited continuations'' to power natural-feeling coroutines. +Because of this, you can invoke your asynchronous code with a small wrapper +around it, and that code will pop off to complete whatever other task it +needs to do, and resume your function when it's ready passing back the +appropriate value. +(No need to manually chain the coroutines together, and no callback hell at +all!) + +Now that's pretty cool! + + + +@node Acknowledgements +@chapter Acknowledgements + +8sync has a number of inspirations: + +@itemize @bullet +@item +@uref{https://docs.python.org/3.5/library/asyncio.html, asyncio} +for Python provides a nice asynchronous programming environment, and +makes great use of generator-style coroutines. +It's a bit more difficult to work with than 8sync (or so thinks the author) +because you have to ``line up'' the coroutines. + +@item +@uref{http://dthompson.us/pages/software/sly.html, Sly} +by David Thompson is an awesome functional reactive game programming +library for Guile. +If you want to write graphical games, Sly is almost certainly a better choice +than 8sync. +Thanks to David for being very patient in explaining tough concepts; +experience on hacking Sly greatly informed 8sync's development. +(Check out Sly, it rocks!) + +@item +Reading @uref{https://mitpress.mit.edu/sicp/, SICP}, particularly +@uref{https://mitpress.mit.edu/sicp/full-text/book/book-Z-H-19.html#%_chap_3, + Chapter 3's writings on concurrent systems}, +greatly informed 8sync's design. + +@item +Finally, @uref{https://docs.python.org/3.5/library/asyncio.html, XUDD} +was an earlier ``research project'' that preceeded 8sync. +It attempted to bring an actor model system to Python. +However, the author eventually grew frustrated with some of Python's +limitations, fell in love with Guile, and well... now we have 8sync, which +is much more general anyway. + +@end itemize + +The motivation to build 8sync came out of +@uref{https://lists.gnu.org/archive/html/guile-devel/2015-10/msg00015.html, + a conversation} +at the FSF 30th party between Mark Weaver, David Thompson, Andrew +Engelbrecht, and Christopher Allan Webber over how to build +an asynchronous event loop for Guile and just what would be needed. + +A little over a month after that, hacking on 8sync began! + + + +@node 8sync's license and general comments on copyleft +@chapter 8sync's license and general comments on copyleft + +8sync is released under the GNU LGPL (Lesser General Public License), +version 3 or later, as published by the Free Software Foundation. +The short version of this is that if you distribute a modifications to +8sync, whether alone or in some larger combination, must release the +corresponding source code. +A program which uses this library, if distributed without source code, +must also allow relinking with a modified version of this library. +In general, it is best to contribute them back to 8sync under the same terms; +we'd appreciate any enhancements or fixes to be contributed upstream to +8sync itself. +(This is an intentional oversimplification for brevity, please read the LGPL +for the precise terms.) + +This usage of the LGPL helps us ensure that 8sync and derivatives of +8sync as a library will remain free. +Though it is not a requirement, we request you use 8sync to build free +software rather than use it to contribute to the growing world of +proprietary software. + +The choice of the LGPL for 8sync was a strategic one. +This is not a general recommendation to use the LGPL instead of the GPL +for all libraries. +In general, we encourage stronger copyleft. +(For more thinking on this position, see +@uref{https://www.gnu.org/licenses/why-not-lgpl.html, + Why you shouldn't use the Lesser GPL for your next library}.) + +Although 8sync provides some unique features, its main functionality is as +an asynchronous event loop, and there are many other asynchronous event +loop systems out there such as Node.js for Javascript and Asyncio for +Python (there are others as well). +It is popular in some of these communities to hold anti-copyleft positions, +which is unfortunate, and many community members seem to be adopting +these positions because other developers they look up to are holding +them. +If you have come from one of these communities and are exploring 8sync, we +hope reading this will help you reconsider your position. + +In particular, if you are building a library or application that uses +8sync in some useful way, consider releasing your program under the GNU +GPL or GNU AGPL! +In a world where more and more software is locked down, where software is used +to restrict users, we could use every chance we can get to provide +protections so that software which is free remains free, and encourages even +more software freedom to be built upon it. + +So to answer the question, ``Can I build a proprietary program on top of +8sync?'' our response is +``Yes, but please don't. +Choose to release your software under a freedom-respecting license. +And help us turn the tide towards greater software freedom... +consider a strong copyleft license!'' + + + +@node Installation +@chapter Installation + +General GNU configure / make / make install instructions go here! +:) + + + +@node Getting started +@chapter Getting started + + + +@node API Reference +@chapter API Reference + + + +@node Contributing +@chapter Contributing + + @node Copying This Manual @appendix Copying This Manual +This manual is licensed under the GNU Free Documentation License, with +no invariant sections. At your option, it is also available under the +GNU Lesser General Public License, as published by the Free Software +Foundation, version 3 or any later version. + + + @menu * GNU Free Documentation License:: License for copying this manual. @end menu