From 1536d0d2f269bb5047bb9bc143038388ac9913fd Mon Sep 17 00:00:00 2001
From: Henri Tuhola <henri.tuhola@gmail.com>
Date: Tue, 29 Dec 2015 03:39:45 +0200
Subject: [PATCH] small fix to the sleep(), and some documentation for
 compiling and recently added functions

---
 doc/index.rst   | 63 +++++++++++++++++++++++++++++++++++++++++++++++++
 runtime/main.py | 23 +++++++++++-------
 2 files changed, 77 insertions(+), 9 deletions(-)

diff --git a/doc/index.rst b/doc/index.rst
index 2e1afee..84add2c 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -19,6 +19,34 @@ Contents:
 
    stdlib
 
+Compiling Instructions
+======================
+
+There are some things that may need explicit platform support and I'll be busy coding
+the first programs in the language. Therefore I only promise that Linux version runs.
+
+At maximum there will be a release for the SteamOS, so you have to compile this
+yourself. If you happen to be a person doing packaging for a distribution, please
+provide your contact info so that I can assist you out and help keep the packaging
+updated effortlessly.
+
+Fortunately the compiling will only take few minutes and it's easy. I have set up a
+script to compile lever. Here's how to invoke it from a terminal::
+
+    cd path/to/lever
+    python setup.py compile
+
+If you're on debian based system, it prompts to install what you need to compile it.
+Otherwise you are adviced to provide the missing dependencies yourself. The script
+won't attempt to proceed if it cannot find the needed libraries.
+
+The compiling results with the executable. For now the run.py -script can be
+used to run any of the examples. Here's how to run one of the samples::
+
+    python run.py samples/ticktock.lc
+
+
+
 Lever base module
 =================
 
@@ -52,6 +80,41 @@ Lever base module
    table, the default -method is called. If there's no default method, then an error
    is raised.
 
+.. class:: greenlet(arguments...)
+
+   Conceptually greenlets represent a body of work you can stop for a moment while
+   you do a different task. Note that you are always in a greenlet. You can always
+   put the current task to sleep, or switch to the eventloop to run a different task.
+
+   Greenlet represents a call frame that can be suspended. The arguments describe a
+   function to call and it can be left blank. In that case the switching has to pass
+   a function that is called inside the greenlet.
+
+   The greenlet.parent describes where the call returns once it finishes.
+
+   greenlet.switch(arguments...) suspends the current greenlet and switches to the
+   targeted greenlet. If the greenlet hasn't started yet, the given arguments are
+   concatenated to the initial arguments. If the greenlet is suspended, the arguments
+   are compacted into a value and returned in the target greenlet.
+
+.. function:: getcurrent()
+
+   Returns the currently running greenlet.
+
+.. function:: schedule(arguments...)
+
+   Schedule is similar to the greenlet -command, except that it queues the greenlet
+   and sets it to return into the eventloop when it finishes. It returns the
+   newly created greenlet.
+
+.. function:: sleep(duration, [function])
+
+   The sleep performs two functions. It can be used to suspend the current greenlet,
+   queue it after duration of seconds pass.
+
+   If you pass it a function or greenlet, it will convert it into a greenlet and
+   adds it to the event queue after the duration passes.
+
 .. class:: int()
 
    An integer. Merely used to identify integers. No other interests.
diff --git a/runtime/main.py b/runtime/main.py
index 85ea341..41c5869 100644
--- a/runtime/main.py
+++ b/runtime/main.py
@@ -85,14 +85,7 @@ def normal_startup(argv):
 @base.builtin
 def schedule(argv):
     ec = get_ec()
-    if len(argv) > 0 and isinstance(argv[0], Greenlet):
-        c = argv.pop(0)
-        assert isinstance(c, Greenlet)
-        c.argv += argv
-    else:
-        c = Greenlet(ec.eventloop, argv)
-    if c.is_exhausted():
-        raise space.Error(u"attempting to put exhausted greenlet into queue")
+    c = to_greenlet(argv)
     ec.queue.append(c)
     return c
 
@@ -126,9 +119,21 @@ def sleep_greenlet(duration):
 def sleep_callback(duration, func):
     ec = get_ec()
     wakeup = time.time() + duration.number
-    ec.sleepers.append(Suspended(wakeup, schedule([func])))
+    ec.sleepers.append(Suspended(wakeup, to_greenlet([func])))
     return space.null
 
+def to_greenlet(argv):
+    ec = get_ec()
+    if len(argv) > 0 and isinstance(argv[0], Greenlet):
+        c = argv.pop(0)
+        assert isinstance(c, Greenlet)
+        c.argv += argv
+    else:
+        c = Greenlet(ec.eventloop, argv)
+    if c.is_exhausted():
+        raise space.Error(u"attempting to put exhausted greenlet into queue")
+    return c
+
 class Greenlet(space.Object):
     def __init__(self, parent, argv):
         self.parent = parent