Merge remote-tracking branch 'origin/master'

README.md

@@ -1,6 +1,6 @@
-[<img src="docs/images/cyclone-logo-04-header.png" alt="cyclone-scheme">](http://justinethier.github.com/cyclone)
+[<img src="docs/images/cyclone-logo-04-header.png" alt="cyclone-scheme">](http://github.com/justinethier/cyclone)
 
-Cyclone is an experimental Scheme-to-C compiler that uses a variant of the [Cheney on the MTA](http://www.pipeline.com/~hbaker1/CheneyMTA.html) technique to implement full tail recursion, continuations, generational garbage collection, and native threads.
+Cyclone is an experimental Scheme-to-C compiler that uses a variant of the [Cheney on the MTA](http://www.pipeline.com/~hbaker1/CheneyMTA.html) technique to implement full tail recursion, continuations, generational garbage collection, and native threads. Unlike previous Cheney on the MTA compilers, Cyclone allows execution of multiple native threads. A tracing garbage collector is used to manage the second-generation heap and perform major collections without "stopping the world".
 
 Getting Started
 ---------------
@@ -38,19 +38,19 @@ Getting Started
 
    You can use [`rlwrap`](http://linux.die.net/man/1/rlwrap) to make the interpreter more friendly, EG: `rlwrap icyc`.
 
-3. If you need help learning the Scheme language try a classic textbook such as [Structure and Interpretation of Computer Programs](https://mitpress.mit.edu/sicp/full-text/book/book.html).
+3. Read the documentation below for detailed information on how to use Cyclone.
-
-   Also, check out the [features](docs/Features.md) page for a list of language features currently implemented.
 
 Documentation
 -------------
 
-[Features](docs/Features.md) is a list of the language features implemented so far. For more information about the Scheme language implemented by Cyclone, see the [R<sup>7</sup>RS Scheme Specification](docs/r7rs.pdf).
+The [User Manual](docs/User-Manual.md) covers in detail how to use Cyclone, and provides information and API documentation on the Scheme language features implemented by Cyclone.
 
 The [Development Guide](docs/Development.md) contains instructions for hacking on Cyclone.
 
 [Writing the Cyclone Scheme Compiler](docs/Writing-the-Cyclone-Scheme-Compiler.md) provides high-level details on how the compiler was written and how it works.
 
+Finally, if you need a place to start learning the Scheme language try a classic textbook such as [Structure and Interpretation of Computer Programs](https://mitpress.mit.edu/sicp/full-text/book/book.html).
+
 References
 ----------
 

api-testing.scm

@@ -0,0 +1,40 @@
+(import 
+  (scheme base)
+  (scheme file)
+  (scheme read)
+  (scheme write)
+  (scheme cyclone util)
+)
+
+;; TODO: this was not working in icyc - wtf?
+;(let ((tmp (call-with-input-file "../scheme/base.sld" 
+;                                (lambda (fp) 
+;                                  (read-all fp)))))
+;  (write
+;   (cdar 
+;    (filter 
+;      (lambda (l) 
+;        (tagged-list? 'export l)) 
+;      (car tmp)))))
+
+(define (read-exports filename)
+  (let* ((tmp (call-with-input-file filename
+                                  (lambda (fp) 
+                                    (read-all fp))))
+         (exports (cdar 
+                    (filter 
+                      (lambda (l) 
+                        (tagged-list? 'export l)) 
+                      (car tmp)))))
+    (write
+    (map
+      (lambda (e)
+        (system 
+          (string-append
+          ;; TODO: not good enough, what about define-syntax?
+            "grep -n \"define[ ]*[ \\(]"
+            (symbol->string e)
+            " \" " filename)))
+      exports)))
+)
+(read-exports "../scheme/file.sld")

docs/API.md

@@ -0,0 +1,30 @@
+
+# R<sup>7</sup>RS Libraries
+
+- Cyclone runtime
+- [`scheme base`](api/scheme/base.md)
+- [`scheme char`](api/scheme/char.md)
+- [`scheme eval`](api/scheme/eval.md)
+- [`scheme file`](api/scheme/file.md)
+- [`scheme load`](api/scheme/load.md)
+- [`scheme process-context`](api/scheme/process-context.md)
+- [`scheme read`](api/scheme/read.md)
+- [`scheme time`](api/scheme/time.md)
+- [`scheme write`](api/scheme/write.md)
+
+# SRFI Support
+
+Cyclone supports the following [Scheme Requests for Implementation (SRFI)](http://srfi.schemers.org/) libraries:
+
+- [`srfi 18`](api/srfi/18.md) - [Multithreading support](http://srfi.schemers.org/srfi-18/srfi-18.html)
+
+# Cyclone-specific
+
+These libraries are used by the Cyclone compiler itself, and are subject to change:
+
+- `scheme cyclone cgen`
+- `scheme cyclone common`
+- `scheme cyclone libraries`
+- `scheme cyclone macros`
+- `scheme cyclone transforms`
+- `scheme cyclone util`

docs/Scheme-Language-Compliance.md

@@ -1,10 +1,6 @@
-# Features
-
-This page summarizes the Scheme language features implemented by Cyclone.
-
 # R<sup>7</sup>RS Compliance
 
-This is the status of Scheme programming language features implemented from the [R<sup>7</sup>RS Scheme Specification](http://trac.sacrideo.us/wg/wiki):
+This is the status of Scheme programming language features implemented from the [R<sup>7</sup>RS Scheme Specification](r7rs.pdf):
 
 Section | Status | Comments
 ------- | ------ | ---------
@@ -41,33 +37,3 @@ Section | Status | Comments
 6.13 Input and output | Partial | Functions do not differentiate between binary and textual ports. Do not have support for input/output strings or bytevectors.
 6.14 System interface | Yes | 
 
-## R<sup>7</sup>RS Libraries
-
-TODO: list each supported library here, and link to a separate page with that library's API as implemented by Cyclone
-
-- scheme base
-- scheme char
-- scheme eval
-- scheme file
-- scheme load
-- scheme process-context
-- [scheme read](api/scheme/read.md)
-- scheme time
-- scheme write
-
-# SRFI Support
-
-Cyclone supports the following [Scheme Requests for Implementation (SRFI)](http://srfi.schemers.org/) libraries:
-
-TODO: [SRFI 18 - Multithreading support](http://srfi.schemers.org/srfi-18/srfi-18.html)
-
-# Cyclone-specific
-
-Cyclone also supports several non-standard features:
-
-- `system`
-- what else?
-
-## FFI
-
-TODO

docs/User-Manual.md

@@ -1,4 +1,4 @@
-[<img src="images/cyclone-logo-04-header.png" alt="cyclone-scheme">](http://justinethier.github.com/cyclone)
+[<img src="images/cyclone-logo-04-header.png" alt="cyclone-scheme">](http://github.com/justinethier/cyclone)
 
 # User Manual
 
@@ -12,15 +12,7 @@
   - [Generated Files](#generated-files)
   - [Interpreter](#interpreter)
 - [Language Details](#language-details)
-  - explain how programs are setup
-  - outline scheme language based on r7rs, link to it.
-    explain differences between cyclone implementation and r7rs, or again at least link to them
-  - provide API, or at least links to the API
-  - what else?
 - [Foreign Function Interface](#foreign-function-interface)
-- Debugging
-  include profiling instructions?
-- Limitations???
 - [Licensing](#licensing)
 - [References and Further Reading](#references-and-further-reading)
 
@@ -28,7 +20,7 @@
 # Introduction
 Cyclone is an experimental Scheme-to-C compiler that uses a variant of the [Cheney on the MTA](http://www.pipeline.com/~hbaker1/CheneyMTA.html) technique to implement full tail recursion, continuations, generational garbage collection, and native threads.
 
-Cyclone works by converting a Scheme program to continuation passing style and compiling each continuation to a C function. At runtime these functions never return and are allowed to fill up the stack until they trigger a minor garbage collection. Live stack objects are then copied to the heap and `longjmp` is used to return to the beginning of the stack. This is the same technique proposed by Henry Baker (Cheney on the MTA) and implemented first by CHICKEN Scheme. The difference here is that multiple native threads are allowed, each with their own stack. A tracing garbage collector is used to manage the second-generation heap and performs major collections without "stopping the world".
+Cyclone works by converting a Scheme program to continuation passing style and compiling each continuation to a C function. At runtime these functions never return and are allowed to fill up the stack until they trigger a minor garbage collection. Live stack objects are then copied to the heap and `longjmp` is used to return to the beginning of the stack. This is the same technique proposed by Henry Baker (Cheney on the MTA) and implemented first by CHICKEN Scheme. The difference is that our compiler allows multiple native threads, each with their own stack. A tracing garbage collector is used to manage the second-generation heap and perform major collections without "stopping the world".
 
 Cyclone is developed by [Justin Ethier](https://github.com/justinethier). 
 
@@ -125,7 +117,11 @@ Scheme code can be evaluated interactively using the `icyc` command:
 
 # Language Details
 
-TODO
+Cyclone implements the Scheme language as documented by the [R<sup>7</sup>RS Scheme Specification](r7rs.pdf). 
+
+A [R<sup>7</sup>RS Compliance Chart](Scheme-Language-Compliance.md) lists differences between the specification and Cyclone's implementation.
+
+[API Documentation](API.md) is available for the libraries provide by Cyclone.
 
 # Foreign Function Interface
 
@@ -148,7 +144,7 @@ The arguments to `define-c` are:
   - `k` - Current continuation, typically the code will call into `k` with a result.
 - A string containing the C function body. Remember that runtime functions are not allowed to return. In the example above, the `return_closcall1` macro is used to "return" a newly-allocated list to the current continuation.
 
-The Cyclone runtime can be used as a reference for how to write your own C functions. A good starting point would be `runtime.c` and `types.h`.
+The Cyclone runtime can be used as a reference for how to write your own C functions. A good starting point would be [`runtime.c`](../runtime.c) and [`types.h`](../include/cyclone/types.h).
 
 # Licensing
 Cyclone is available under the [MIT license](http://www.opensource.org/licenses/mit-license.php).

docs/api/scheme/base.md

@@ -0,0 +1,5 @@
+# Base Library
+
+The `(scheme base)` library exports many of the procedures and syntax bindings that are traditionally associated with Scheme.
+
+TODO: list functions

docs/api/scheme/char.md

@@ -0,0 +1,15 @@
+# Char Library
+
+The `(scheme char)` library provides the procedures for dealing with characters.
+
+- `char-alphabetic?`
+- `char-downcase`
+- `char-lower-case?`
+- `char-numeric?`
+- `char-upcase`
+- `char-upper-case?`
+- `char-whitespace?`
+- `digit-value`
+- `string-upcase`
+- `string-downcase`
+

docs/api/scheme/eval.md

@@ -0,0 +1,8 @@
+# Eval Library
+
+The `(scheme eval)` library exports procedures for evaluating
+Scheme data as programs.
+
+- `eval`
+- `create-environment`
+- `setup-environment`

docs/api/scheme/file.md

@@ -0,0 +1,12 @@
+# File Library
+
+The `(scheme file)` library provides procedures for accessing
+files.
+
+- `call-with-input-file`
+- `call-with-output-file`
+- `delete-file`
+- `file-exists?`
+- `with-input-from-file` 
+- `with-output-to-file`
+

docs/api/scheme/load.md

@@ -0,0 +1,13 @@
+# Load Library
+
+The `(scheme load)` library exports procedures for loading Scheme expressions from files.
+
+- [`load`](#load)
+
+#load
+
+    (load filename)
+
+The `load` procedure reads expressions and definitions from the file and evaluates them sequentially.
+
+Note that when using `load` in a compiled program, the file will be processed at runtime using `eval`. The file contents will not be compiled.

docs/api/scheme/process-context.md

@@ -0,0 +1,9 @@
+# Process-Context Library
+
+The `(scheme process-context)` library exports procedures
+for accessing with the program's calling context.
+
+- `command-line`
+- `emergency-exit`
+- `exit`
+- `get-environment-variable`

docs/api/scheme/read.md

@@ -10,6 +10,8 @@ The `(scheme read)` library provides procedures for reading Scheme objects.
     (read)
     (read port)
 
+Read a single Scheme object from the input port.
+
 #read-all
 
     (read-all)

docs/api/scheme/time.md

@@ -0,0 +1,7 @@
+# Time Library
+
+The `(scheme time)` library provides access to time-related values.
+
+- `current-jiffy`
+- `current-second`
+- `jiffies-per-second`

docs/api/scheme/write.md

@@ -0,0 +1,18 @@
+# Write Library
+
+The `(scheme write)` library provides procedures for writing
+Scheme objects.
+
+- [`display`](#display)
+- `write`
+
+#display
+
+    (display)
+    (display port)
+
+#write
+
+    (write)
+    (write port)
+

docs/api/srfi/18.md

@@ -0,0 +1,12 @@
+# SRFI 18 - Multithreading support
+
+The `(srfi 18)` library provides multithreading support. See the [SRFI document](http://srfi.schemers.org/srfi-18/srfi-18.html) for more information.
+
+- `thread?`
+- `make-thread`
+- `thread-name`
+- `thread-specific`
+- `thread-specific-set!`
+- `thread-start!`
+- `thread-yield!`
+

gc-notes.txt

@@ -7,8 +7,7 @@ Phase 6 (gc-dev6) - Multiple mutators (application threads)
 Phase 7 (TBD) - Sharing of variables between threads (ideally without limitation, but that might not be realistic)
 
 TODO:
-- bring exceptions into local thread data? anything else?
+- will probably need to lock shared resources such as I/O...
-  also, will probably need to lock shared resources such as I/O...
   Yes, anything global needs to be considered.
   These will certainly need to change:
   - read.sld in-port-table - obvious thread safety issue here
@@ -18,12 +17,16 @@ TODO:
     crashes, I think printing out result from (read)
   - assume I/O and eval both have threading issues
   - eval.sld - ...
+- In conjunction with above, write more programs that use multiple threads
+  - try a simple one with 3-6 threads just writing data to output, and then files
+  - simple multithreaded example such as producer/consumer
+  - find at least one more algorithm that can be parallelized
 - document at a high level how the GC works
   mostly what minor/major GC's are, and how they are interleaved.
 - user manual
   need to document everything, including:
-  - how to use cyclone (meta files, compiling modules, etc)
   - what to be cognizant of when writing threading code. esp, how to deal with stack objects (initiating minor GC's, etc)
+    this probably should be part of the user manual itself
 - revisit features list, issues list, etc
 
 DONE: