Permalink
Browse files

update readme

  • Loading branch information...
1 parent b41b255 commit 61fb9160c2ba1a333b74dbd7f11e7ee41f7e3a1f @ninjudd ninjudd committed May 12, 2011
Showing with 30 additions and 16 deletions.
  1. +29 −15 README.md
  2. +1 −1 project.clj
View
@@ -2,12 +2,24 @@ Portal is a unified REPL and command server for Clojure.
# Protocol
-Portal uses netstrings to encode messages<sup><a name="ref1" href="#fn1">1</a></sup>. This makes
-client implementations as simple as possible. The format of an individual message is as follows:
+Portal uses [netstrings](http://en.wikipedia.org/wiki/Netstring) to encode messages<sup><a
+name="ref1" href="#fn1">1</a></sup>. This allows client implementations to be as simple as possible.
- id type data
+A netstring consists of prefix with the byte length of the message that follows. The prefix is
+separated from the message by a colon and each message is separated by a comma. Here is a simple
+netstring:
-The `id` is a string identifier used to determine which evaluation context to use. The context is
+ 18:The cake is a lie!,
+
+The format of an individual portal message is as follows:
+
+ ID TYPE DATA
+
+Where each element is separated by a single space.
+
+#### ID
+
+`ID` is a string identifier used to determine which evaluation context to use. The context is
used to maintain state across multiple commands and has a unique stdin, stdout and stderr from other
contexts. It is helpful to think of each context as executing in a dedicated thread, though actually
agents are used to implement contexts, so a thread pool is shared among all contexts.
@@ -16,20 +28,22 @@ In addition, all commands within a given context are serialized so they happen i
received, and one command cannot start until the previous command for that context finishes. Of
course, you can call commands asynchronously though by using unique ids.
-For client requests `type` can be one of:
+#### TYPE
+
+For client requests `TYPE` can be one of:
-* `eval` - Evaluate the forms provided in `data`.
-* `stdin` - Write the string provided in `data` to `*in*`.
-* `clear` - Clear the context for `id`.
-* `fork` - Associate the context for `id` with the id provided in `data`.
+ eval - Evaluate the forms provided in DATA.
+ stdin - Write the string provided in DATA to *in*.
+ clear - Clear the context for ID.
+ fork - Associate the context for ID with the id provided in DATA.
-For server responses `type` can be one of:
+For server responses `TYPE` can be one of:
-* `result` - Evaluation completed with no errors. The results are provided in `data`
-* `error` - There was an exception during evaluation. The error type and message are provided in `data`.
-* `read-error` - There was an error while reading the forms. The error message is provided in `data`.
-* `stdout` - The string in `data` was printed to `*out*` during evaluation.
-* `stderr` - The string in `data` was printed to `*err*` during evaluation.
+ result - Evaluation completed with no errors. The results are provided in DATA.
+ error - There was an exception during evaluation. The error type and message are provided in DATA.
+ read-error - There was an error while reading the forms. The error message is provided in DATA.
+ stdout - The string in DATA was printed to *out* during evaluation.
+ stderr - The string in DATA was printed to *err* during evaluation.
# Client Libraries
View
@@ -1,4 +1,4 @@
(defproject portal "0.0.1-SNAPSHOT"
- :description "A remote evaluation library for Clojure."
+ :description "The cake is a lie!"
:dependencies [[clojure "1.2.0"]
[aleph "0.1.5-SNAPSHOT"]])

0 comments on commit 61fb916

Please sign in to comment.