diff --git a/README.md b/README.md index bfae68d5..0d7c4813 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ -[cyclone-scheme](http://justinethier.github.com/cyclone) +[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). - - Also, check out the [features](docs/Features.md) page for a list of language features currently implemented. +3. Read the documentation below for detailed information on how to use Cyclone. 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 [R7RS 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 ---------- diff --git a/api-testing.scm b/api-testing.scm new file mode 100644 index 00000000..78ca85e3 --- /dev/null +++ b/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") diff --git a/docs/API.md b/docs/API.md new file mode 100644 index 00000000..7a69ce84 --- /dev/null +++ b/docs/API.md @@ -0,0 +1,30 @@ + +# R7RS 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` diff --git a/docs/Features.md b/docs/Scheme-Language-Compliance.md similarity index 76% rename from docs/Features.md rename to docs/Scheme-Language-Compliance.md index dc11f490..6e0cdf27 100644 --- a/docs/Features.md +++ b/docs/Scheme-Language-Compliance.md @@ -1,10 +1,6 @@ -# Features - -This page summarizes the Scheme language features implemented by Cyclone. - # R7RS Compliance -This is the status of Scheme programming language features implemented from the [R7RS Scheme Specification](http://trac.sacrideo.us/wg/wiki): +This is the status of Scheme programming language features implemented from the [R7RS 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 | -## R7RS 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 diff --git a/docs/User-Manual.md b/docs/User-Manual.md index 767e339b..7a1384de 100644 --- a/docs/User-Manual.md +++ b/docs/User-Manual.md @@ -1,4 +1,4 @@ -[cyclone-scheme](http://justinethier.github.com/cyclone) +[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 [R7RS Scheme Specification](r7rs.pdf). + +A [R7RS 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). diff --git a/docs/api/scheme/base.md b/docs/api/scheme/base.md new file mode 100644 index 00000000..030bb6b9 --- /dev/null +++ b/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 diff --git a/docs/api/scheme/char.md b/docs/api/scheme/char.md new file mode 100644 index 00000000..f3f8e772 --- /dev/null +++ b/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` + diff --git a/docs/api/scheme/eval.md b/docs/api/scheme/eval.md new file mode 100644 index 00000000..c4a4feb1 --- /dev/null +++ b/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` diff --git a/docs/api/scheme/file.md b/docs/api/scheme/file.md new file mode 100644 index 00000000..d3246129 --- /dev/null +++ b/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` + diff --git a/docs/api/scheme/load.md b/docs/api/scheme/load.md new file mode 100644 index 00000000..a8b3968d --- /dev/null +++ b/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. diff --git a/docs/api/scheme/process-context.md b/docs/api/scheme/process-context.md new file mode 100644 index 00000000..f27b01f8 --- /dev/null +++ b/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` diff --git a/docs/api/scheme/read.md b/docs/api/scheme/read.md index bedbf5b2..24b235a8 100644 --- a/docs/api/scheme/read.md +++ b/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) diff --git a/docs/api/scheme/time.md b/docs/api/scheme/time.md new file mode 100644 index 00000000..0b6b03b6 --- /dev/null +++ b/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` diff --git a/docs/api/scheme/write.md b/docs/api/scheme/write.md new file mode 100644 index 00000000..77c5f7d4 --- /dev/null +++ b/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) + diff --git a/docs/api/srfi/18.md b/docs/api/srfi/18.md new file mode 100644 index 00000000..9ea57c84 --- /dev/null +++ b/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!` + diff --git a/gc-notes.txt b/gc-notes.txt index e16953cc..3d628670 100644 --- a/gc-notes.txt +++ b/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? - also, will probably need to lock shared resources such as I/O... +- 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: