From f25bce43c713ff05d9886798a992aa88296a0a57 Mon Sep 17 00:00:00 2001 From: Justin Ethier Date: Wed, 13 Jan 2016 21:57:12 -0500 Subject: [PATCH 01/22] WIP --- docs/api/scheme/read.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/api/scheme/read.md b/docs/api/scheme/read.md index bedbf5b2..175b6bf6 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) +[test](../../../scheme/read.sld#L441) + #read-all (read-all) From c9cc8a1ce57a33fb68b04b624c03015d744a9502 Mon Sep 17 00:00:00 2001 From: Justin Ethier Date: Wed, 13 Jan 2016 22:03:17 -0500 Subject: [PATCH 02/22] Extracting API and r7rs compatibility --- docs/API.md | 34 ++++++++++++++++++ ...tures.md => Scheme-Language-Compliance.md} | 36 +------------------ 2 files changed, 35 insertions(+), 35 deletions(-) create mode 100644 docs/API.md rename docs/{Features.md => Scheme-Language-Compliance.md} (76%) diff --git a/docs/API.md b/docs/API.md new file mode 100644 index 00000000..b415bdd9 --- /dev/null +++ b/docs/API.md @@ -0,0 +1,34 @@ + +# 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 + +## Built-ins +Cyclone also supports several non-standard features: + +- `system` +- what else? + +## Cyclone API + +# FFI + +TODO 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 From f3663c74024c9658a18406d0b8b1acc35d7ae17c Mon Sep 17 00:00:00 2001 From: Justin Ethier Date: Wed, 13 Jan 2016 22:08:49 -0500 Subject: [PATCH 03/22] Link to user manual --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index bfae68d5..a7acb041 100644 --- a/README.md +++ b/README.md @@ -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 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 ---------- From 80975f7ca38aab633b307c349361fe189d798471 Mon Sep 17 00:00:00 2001 From: Justin Ethier Date: Wed, 13 Jan 2016 22:09:15 -0500 Subject: [PATCH 04/22] Revised wording --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index a7acb041..b41b0de4 100644 --- a/README.md +++ b/README.md @@ -38,7 +38,7 @@ Getting Started You can use [`rlwrap`](http://linux.die.net/man/1/rlwrap) to make the interpreter more friendly, EG: `rlwrap icyc`. -3. Read the documentation for detailed information on how to use Cyclone. +3. Read the documentation below for detailed information on how to use Cyclone. Documentation ------------- From 678d84e358746083297272ae61ccb0e3740bb24e Mon Sep 17 00:00:00 2001 From: Justin Ethier Date: Wed, 13 Jan 2016 22:25:36 -0500 Subject: [PATCH 05/22] Revisions --- docs/User-Manual.md | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/docs/User-Manual.md b/docs/User-Manual.md index 767e339b..e2c61f6f 100644 --- a/docs/User-Manual.md +++ b/docs/User-Manual.md @@ -12,11 +12,6 @@ - [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? @@ -28,7 +23,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 in our compiler 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 perform major collections without "stopping the world". Cyclone is developed by [Justin Ethier](https://github.com/justinethier). @@ -125,6 +120,16 @@ Scheme code can be evaluated interactively using the `icyc` command: # Language Details +[R7RS Scheme Specification](r7rs.pdf): +[R7RS Compliance](Scheme-Language-Compliance.md) +[API Documentation](API.md) + + - 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? + TODO # Foreign Function Interface From 964ccfc361fa7182fa978ab20d1b226dddcece9e Mon Sep 17 00:00:00 2001 From: Justin Ethier Date: Wed, 13 Jan 2016 23:28:10 -0500 Subject: [PATCH 06/22] Adding new script as a possible new tool --- api-testing.scm | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 api-testing.scm 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") From 4b2a4575d0b3002b2292a988e2d38f802f675166 Mon Sep 17 00:00:00 2001 From: Justin Ethier Date: Wed, 13 Jan 2016 23:28:56 -0500 Subject: [PATCH 07/22] Link to API files --- docs/User-Manual.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/User-Manual.md b/docs/User-Manual.md index e2c61f6f..fe39fa71 100644 --- a/docs/User-Manual.md +++ b/docs/User-Manual.md @@ -153,7 +153,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). From 1312d1819ac6a00d9feefcae0092fc18aaa807b1 Mon Sep 17 00:00:00 2001 From: Justin Ethier Date: Wed, 13 Jan 2016 23:32:59 -0500 Subject: [PATCH 08/22] WIP --- docs/User-Manual.md | 12 ++---------- 1 file changed, 2 insertions(+), 10 deletions(-) diff --git a/docs/User-Manual.md b/docs/User-Manual.md index fe39fa71..a0bc8b45 100644 --- a/docs/User-Manual.md +++ b/docs/User-Manual.md @@ -120,17 +120,9 @@ Scheme code can be evaluated interactively using the `icyc` command: # Language Details -[R7RS Scheme Specification](r7rs.pdf): -[R7RS Compliance](Scheme-Language-Compliance.md) -[API Documentation](API.md) +Cyclone implements the Scheme language as documented by the [R7RS Scheme Specification](r7rs.pdf). There is a [R7RS Compliance](Scheme-Language-Compliance.md) chart that lists the differences between the specification and Cyclone's implementation. - - 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? - -TODO +[API Documentation](API.md) is available for the libraries provide by Cyclone. # Foreign Function Interface From 1befee8d9882871ab04cb48b4ba670ca9541a78d Mon Sep 17 00:00:00 2001 From: Justin Ethier Date: Wed, 13 Jan 2016 23:35:14 -0500 Subject: [PATCH 09/22] WIP --- docs/User-Manual.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/User-Manual.md b/docs/User-Manual.md index a0bc8b45..3bd03caf 100644 --- a/docs/User-Manual.md +++ b/docs/User-Manual.md @@ -120,7 +120,9 @@ Scheme code can be evaluated interactively using the `icyc` command: # Language Details -Cyclone implements the Scheme language as documented by the [R7RS Scheme Specification](r7rs.pdf). There is a [R7RS Compliance](Scheme-Language-Compliance.md) chart that lists the differences between the specification and Cyclone's implementation. +Cyclone implements the Scheme language as documented by the [R7RS Scheme Specification](r7rs.pdf). + +In addition there is a [R7RS Compliance Chart](Scheme-Language-Compliance.md) that lists differences between the specification and Cyclone's implementation. [API Documentation](API.md) is available for the libraries provide by Cyclone. From 0f9cb6a694c0e8ef01e84adae5f5d453f01a96b3 Mon Sep 17 00:00:00 2001 From: Justin Ethier Date: Wed, 13 Jan 2016 23:38:18 -0500 Subject: [PATCH 10/22] WIP --- docs/User-Manual.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/docs/User-Manual.md b/docs/User-Manual.md index 3bd03caf..ab2b1246 100644 --- a/docs/User-Manual.md +++ b/docs/User-Manual.md @@ -13,9 +13,6 @@ - [Interpreter](#interpreter) - [Language Details](#language-details) - [Foreign Function Interface](#foreign-function-interface) -- Debugging - include profiling instructions? -- Limitations??? - [Licensing](#licensing) - [References and Further Reading](#references-and-further-reading) @@ -122,7 +119,7 @@ Scheme code can be evaluated interactively using the `icyc` command: Cyclone implements the Scheme language as documented by the [R7RS Scheme Specification](r7rs.pdf). -In addition there is a [R7RS Compliance Chart](Scheme-Language-Compliance.md) that lists differences between the specification and Cyclone's implementation. +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. From 7ffb609147b374430a4e9d9aef45acca01c5ac7f Mon Sep 17 00:00:00 2001 From: Justin Ethier Date: Wed, 13 Jan 2016 23:40:42 -0500 Subject: [PATCH 11/22] Fixed links --- README.md | 2 +- docs/User-Manual.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index b41b0de4..f892b3b4 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -[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. diff --git a/docs/User-Manual.md b/docs/User-Manual.md index ab2b1246..88bb2fb1 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 From 326dc9688d6a3546043443a761d6b51200e1a266 Mon Sep 17 00:00:00 2001 From: Justin Ethier Date: Wed, 13 Jan 2016 23:42:49 -0500 Subject: [PATCH 12/22] TODO's --- docs/API.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/API.md b/docs/API.md index b415bdd9..b100f3ef 100644 --- a/docs/API.md +++ b/docs/API.md @@ -1,7 +1,7 @@ # R7RS Libraries -TODO: list each supported library here, and link to a separate page with that library's API as implemented by Cyclone +TODO: - scheme base - scheme char @@ -17,7 +17,9 @@ TODO: list each supported library here, and link to a separate page with that li 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) +## [SRFI 18 - Multithreading support](http://srfi.schemers.org/srfi-18/srfi-18.html) + +TODO: # Cyclone-specific @@ -29,6 +31,5 @@ Cyclone also supports several non-standard features: ## Cyclone API -# FFI +TODO: -TODO From 98cd04853c60bf7bfd25f7e669ab89abfef20852 Mon Sep 17 00:00:00 2001 From: Justin Ethier Date: Thu, 14 Jan 2016 02:34:18 -0500 Subject: [PATCH 13/22] Initial file --- docs/api/scheme/base.md | 5 +++++ docs/api/scheme/char.md | 15 +++++++++++++++ docs/api/scheme/eval.md | 8 ++++++++ docs/api/scheme/file.md | 12 ++++++++++++ docs/api/scheme/load.md | 13 +++++++++++++ docs/api/scheme/process-context.md | 9 +++++++++ docs/api/scheme/read.md | 2 +- docs/api/scheme/time.md | 7 +++++++ docs/api/scheme/write.md | 18 ++++++++++++++++++ 9 files changed, 88 insertions(+), 1 deletion(-) create mode 100644 docs/api/scheme/base.md create mode 100644 docs/api/scheme/char.md create mode 100644 docs/api/scheme/eval.md create mode 100644 docs/api/scheme/file.md create mode 100644 docs/api/scheme/load.md create mode 100644 docs/api/scheme/process-context.md create mode 100644 docs/api/scheme/time.md create mode 100644 docs/api/scheme/write.md 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 175b6bf6..24b235a8 100644 --- a/docs/api/scheme/read.md +++ b/docs/api/scheme/read.md @@ -10,7 +10,7 @@ The `(scheme read)` library provides procedures for reading Scheme objects. (read) (read port) -[test](../../../scheme/read.sld#L441) +Read a single Scheme object from the input port. #read-all diff --git a/docs/api/scheme/time.md b/docs/api/scheme/time.md new file mode 100644 index 00000000..022066e4 --- /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) + From b87bdda7eecb0de017a71b445555ec14c4fa0a95 Mon Sep 17 00:00:00 2001 From: Justin Ethier Date: Thu, 14 Jan 2016 02:35:32 -0500 Subject: [PATCH 14/22] Link to new docs --- docs/API.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/API.md b/docs/API.md index b100f3ef..23076497 100644 --- a/docs/API.md +++ b/docs/API.md @@ -3,15 +3,15 @@ TODO: -- scheme base -- scheme char -- scheme eval -- scheme file -- scheme load -- scheme process-context +- [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 -- scheme write +- [scheme time](api/scheme/time.md) +- [scheme write](api/scheme/write.md) # SRFI Support From 4b18045e1932832727223343a8c270cdea6c87ad Mon Sep 17 00:00:00 2001 From: Justin Ethier Date: Thu, 14 Jan 2016 02:37:21 -0500 Subject: [PATCH 15/22] Fixes --- docs/API.md | 18 +++++++++--------- docs/api/scheme/time.md | 2 +- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/API.md b/docs/API.md index 23076497..5f4feb02 100644 --- a/docs/API.md +++ b/docs/API.md @@ -3,15 +3,15 @@ TODO: -- [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) +- [`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 diff --git a/docs/api/scheme/time.md b/docs/api/scheme/time.md index 022066e4..0b6b03b6 100644 --- a/docs/api/scheme/time.md +++ b/docs/api/scheme/time.md @@ -1,6 +1,6 @@ # Time Library -The `(scheme time` library provides access to time-related values. +The `(scheme time)` library provides access to time-related values. - `current-jiffy` - `current-second` From 39f8096a620c613aa48589f20f9c8eac36609471 Mon Sep 17 00:00:00 2001 From: Justin Ethier Date: Thu, 14 Jan 2016 02:37:43 -0500 Subject: [PATCH 16/22] WIP --- docs/API.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/API.md b/docs/API.md index 5f4feb02..df5e8e97 100644 --- a/docs/API.md +++ b/docs/API.md @@ -1,8 +1,6 @@ # R7RS Libraries -TODO: - - [`scheme base`](api/scheme/base.md) - [`scheme char`](api/scheme/char.md) - [`scheme eval`](api/scheme/eval.md) From a7546074cb0c0cc311df1c1e871725189786b269 Mon Sep 17 00:00:00 2001 From: Justin Ethier Date: Thu, 14 Jan 2016 02:58:47 -0500 Subject: [PATCH 17/22] Added more content --- docs/API.md | 21 +++++++++------------ 1 file changed, 9 insertions(+), 12 deletions(-) diff --git a/docs/API.md b/docs/API.md index df5e8e97..7a69ce84 100644 --- a/docs/API.md +++ b/docs/API.md @@ -1,6 +1,7 @@ # R7RS Libraries +- Cyclone runtime - [`scheme base`](api/scheme/base.md) - [`scheme char`](api/scheme/char.md) - [`scheme eval`](api/scheme/eval.md) @@ -15,19 +16,15 @@ Cyclone supports the following [Scheme Requests for Implementation (SRFI)](http://srfi.schemers.org/) libraries: -## [SRFI 18 - Multithreading support](http://srfi.schemers.org/srfi-18/srfi-18.html) - -TODO: +- [`srfi 18`](api/srfi/18.md) - [Multithreading support](http://srfi.schemers.org/srfi-18/srfi-18.html) # Cyclone-specific -## Built-ins -Cyclone also supports several non-standard features: - -- `system` -- what else? - -## Cyclone API - -TODO: +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` From b8f0691bda60f1cf4c50662daeb902cd02df55ca Mon Sep 17 00:00:00 2001 From: Justin Ethier Date: Thu, 14 Jan 2016 03:02:32 -0500 Subject: [PATCH 18/22] New file --- docs/api/srfi/18.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) create mode 100644 docs/api/srfi/18.md 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!` + From 0cee4e75b443c0e09749c04490add0a7943715a1 Mon Sep 17 00:00:00 2001 From: Justin Ethier Date: Thu, 14 Jan 2016 03:06:51 -0500 Subject: [PATCH 19/22] Revised wording --- docs/User-Manual.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/User-Manual.md b/docs/User-Manual.md index 88bb2fb1..7a1384de 100644 --- a/docs/User-Manual.md +++ b/docs/User-Manual.md @@ -20,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 in our compiler 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 perform 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). From 9fe6510334b873892825cae557c76ed2f9fda5e9 Mon Sep 17 00:00:00 2001 From: Justin Ethier Date: Thu, 14 Jan 2016 03:09:18 -0500 Subject: [PATCH 20/22] Expanded description --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index f892b3b4..903d3e83 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ [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 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". Getting Started --------------- From 5752080968b7313e092a37f1e8103031a500579d Mon Sep 17 00:00:00 2001 From: Justin Ethier Date: Thu, 14 Jan 2016 03:10:50 -0500 Subject: [PATCH 21/22] Revised --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 903d3e83..0d7c4813 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ [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. Unlike previous Cheney on the MTA compilers, Cyclone 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 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 --------------- From b2a7b6ec23eeb1df7d4aafcab8d2a6198ccd669c Mon Sep 17 00:00:00 2001 From: Justin Ethier Date: Thu, 14 Jan 2016 03:20:57 -0500 Subject: [PATCH 22/22] Refining TODO list --- gc-notes.txt | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) 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: