flok 0.0.12 → 0.0.14

data/docs/messaging.md

@@ -0,0 +1,110 @@
+#Messaging
+Flok uses two endpoints named `if_dispatch` and `int_dispatch` to communicate between the flok server and client. When the flok server wants to message the client, the flok server
+calls `if_dispatch`.  When the client wants to message the flok server, the client calls `int_disptach`. These two receive virtually the same formats
+with the difference being that `if_dispatch` receives a multi-array queue where each array has a number pre-pended to the front that indicates the
+queue the message is supposed to be interpreted in. `int_dispatch` always run synchronously, so it does not have a multi-dimensional array, only one
+array that has no integer in the front.
+
+#Scheme
+Each message is composed of 3 parts.
+
+`[arg_length, function_name, *args]`
+ * arg_length - How many argugments are in *args
+ * message_name - What message type (function) is this?
+ * *args - A list of arguments that are being sent to the function (any type, including hashes are supported)
+
+Multiple messages can be coalesced by just appending them to the same (flat) array.
+
+###Examples
+Here are some simple examples
+
+```js
+//3+4
+[2, "sum", 3, 4]
+
+//sqrt(12)
+[1, "sqrt", 12]
+
+//3+4 and then sqrt(12)
+[2, "sum", 3, 4, 1, "sqrt", 12]
+```
+
+### How messages are handled
+On the server, all messages come through `int_dispatch`. Messages are then turned into function calls by using the
+`message_name` as the function name and parameters are passed via `apply`.  All functions that are caled in this manner
+live in `./app/kern/mod/` and have the convention of being called `int_*`.
+
+On the client, the driver decides on how messages are handled. At a minimum, the client must support the `if_dispatch` function
+call. The driver is given a queue suggestion based on the first number for each message queue in the `if_dispatch` call. See
+[Scheduling](./scheduling.md) for more information.
+
+### Ping
+Both the client and server are responsible for being able to reply to a few test messages.
+
+#####For the client
+  - Given `[[0, 0, "ping"]]` respond with `[0, pong]`
+  - Given `[[0, 1, "ping1", arg]]` respond with `[1, pong1, arg]`
+  - Given `[[0, 2, "ping2", arg1, arg2]]` respond with `[1, "pong2", arg1]` and `[2, "pong2", arg1, arg2]`
+  - Given `[[0, 2, "ping2", arg1, arg2]]` respond with `[1, "pong2", arg1]` and `[2, "pong2", arg1, arg2]`
+  - Given `[[0, 0, "ping", 0, "ping"]]` respond with `[0, "pong"]` and `[0, "pong"]`
+  - Given `[[0, 1, "ping1", secret1, 1, "ping1", secret2]]` respond with `[1, "pong1", secret1]` and `[1, "pong1", secret2]` 
+  - Given `[[0, 1, "ping1", secret1, 1, "ping1", secret2]]` respond with `[1, "pong1", secret1]` and `[1, "pong1", secret2]` 
+  - Given `[[0, 2, "ping2", secret1, secret2, 2, "ping2", secret2, secret1]]` respond with:
+    1. `[1, "pong2", secret1]` 
+    2. `[2, "pong2", secret1, secret2]` 
+    3. `[1, "pong2", secret2]` 
+    4. `[2, "pong2", secret2, secret1]`
+
+#####For the server
+  - Given `[0, "ping"]` respond with `[[0, 0, pong]]`
+  - Given `[1, "ping1", arg]` respond with `[[0, 1, pong1, arg]]`
+  - Given `[2, "ping2", arg1, arg2]]` respond with `[[0, 1, "pong2", arg1, 2, "pong2", arg1, arg2]]`
+  - Given `[2, "ping2", arg1, arg2]]` respond with `[[0, 1, "pong2", arg1, 2, "pong2", arg1, arg2]]`
+  - Given `[0, "ping", 0, "ping"]` respond with `[[0, 0, "pong", 0, "pong"]]`
+  - Given `[1, "ping1", secret1, 1, "ping1", secret2]` respond with `[[0, 1, "pong1", secret1, 1, "pong1", secret2]]` 
+  - Given `[1, "ping1", secret1, 1, "ping1", secret2]` respond with `[[0, 1, "pong1", secret1, 1, "pong1", secret2]]` 
+  - Given `[2, "ping2", secret1, secret2, 2, "ping2", secret2, secret1]` respond with:
+    - `[[0, 1, "pong2", secret1, 2, "pong2", secret1, secret2, 1, "pong2", secret2, 2, "pong2", secret2, secret1]]` 
+  - Given `[1, "ping3", queue_name]` respond with `[[queue_index, 0, "pong3"]]`
+  - Given `[1, "ping3", queue_nameA, 1, "ping3", queue_nameA, 1, "ping3", queue_nameB]` respond with `[[queue_indexA, 0, "pong3", 0, "pong3"], [queue_indexB, 0, "pong3"]]`
+  - Given `[1, "ping3", queue_name]` respond with `[[queue_index, 0, "pong3"]]` and then given `[1, "ping3", queue_name]` respond with `[[queue_index, 0, "pong3"]]`
+  - Given `[1, "ping4", queue_index]x6` respond with `[[queue_index, *[0, "pong4"]*5]]
+      - Then given `[1, "ping4", queue_index]` respond with `[]`
+	  - Given `[0, "ping4_int"]` respond with `[[queue_index, 0, "pong4"]]`
+  - *If the queue_index is 0 (main), it should queue all 6*
+
+### Protocols
+Protocols are informal conventions used in Flok when sending certain messages.
+
+##### @telepathy(2)
+  1. `[N+2, "if_*", ... , tp_base, tp_targets, ...]` - Multiple targets
+  2. `[N+1, "if_*", ..., tp_base, ...]` - One target (acts as same above but only one target)
+
+This protocol supports virtual de-referencing.  When an entity is initialized, the server notifies the client that it (the client) should be able to dereference that entity via the telepathic pointer (tele-pointer for short) the server
+just gave in the initialization.
+
+For most clients, this would work via having a global hash table that can relate the telepathic pointers to native pointers.
+Here is an example de-reference table:
+```ruby
+[tp    native_addr]
+ 0     0x30203023
+ 1     0x12040212
+ ```
+
+The client receives to arguments in the message, 
+  1.  `tp_base` - The *base* pointer
+  2.  `tp_targets` - An array that contains the names of all the objects that need to be accessible via a tele-pointer.
+
+An example of these arguments could be:
+  1.  `tp_base` - 33
+  2.  `tp_targets` - ['main_view', 'content']
+
+These arguments are saying that the *first* pointer will be given the address `33` and needs to refer to the `main_view`.
+The *second* pointer will be given the address `34`, you increment the pointer by 1 each new target. `34` will refer to the `content`
+```ruby
+[tp    native_addr]
+ 33     0x10ab4022(&mainView)
+ 34     0x10ab3012(&content)
+ ```
+
+On the server side, the `tp_base` comes from calling `tels(n)` where `n` is the number of targets you will need.

data/docs/mod/controller.md

@@ -0,0 +1,35 @@
+#Controller (controller.js)
+
+### Depends
+  * ui.js - The controller module depends on the `ui` module as it passes a pointer to a view in `if_controller_init`
+
+### Functions
+`if_controller_init(bp, rvp, name, context)` - Initialize a controller that manages the view at `rvp` and contains the address `bp`. All events are sent to `bp` should be handled appropriatlely.
+The `rvp` pointer will always be an initialized (but not attached) view. When receiving an action, the view is guaranteed to be attached at that time. Context is what the controller was initialized with.
+
+### Spec helpers
+
+### Controller Destruction
+Controllers are bound to the lifetime of the view contained at `rvp`.  When `if_free_view` is called, the controller is expected to be removed on the `device` side.
+
+### Events
+All controller information is passed through events via `if_event`. When a controller receives an event, some events have
+special meanings based on the `name` field of the event:
+  1. `action` - The action has changed (on entered). This is also called after if_controller_init with `null`. Action is **always** called with an
+  attached view. 
+    * `from` - A string that represents the 'from' action we came from, it may be null
+    * `to`   - A string that represents the 'to' action we are going to, it is never null
+    * `info` - A hash with information for the new action
+  2. Everything else is a `custom event` and must be handeled accordingly
+
+### Spec messages (driver side)
+`if_spec_controller_init` - Setup anything necessary for the spec tests, this may include adding prototype controller js (for chrome), etc
+`if_spec_controller_list` - Sends a message back called `spec` that contains an array of controller base pointers that were initialized via `if_controller_init`
+but have not been destroyed.
+
+### Spec fixtures (driver side)
+There should be a special controller called `__test__` that can be initialized and should respond in the following ways when it receives an action and
+event:
+  Note: an event is **not** a raw message, it is through the message of `int_event`, i.e. `[3, "int_event", "event_name", info]`
+  Sends a **event** back called `action_rcv` containing `{from: from, to: to, info: info}` when an action is received
+  Sends a **event** back called `custom_rcv` containing a hash that looks like `{name: name, info: event}` when a custom event is received

data/docs/mod/debug.md

@@ -0,0 +1,32 @@
+#Debug (debug.js)
+The debug module provides information to the client (driver) module such as events that are available for a particular view.
+
+### Driver Messages
+`if_debug_assoc(base, key, value)` - Associate a key and value for an object called base (usually a pointer or string)
+
+`if_debug_highlight_view(vp, on)` - Highlight the view **or spot** that is given in `vp`. Used in some debuggers (like seagull) to let users select
+the hierarchy and see it's equivalent in the client. `on` is a bool that indicates whether something should be highlihted or not. (toggle).
+If given a view pointer that's 0 or dosen't exist, it should just ignore it.
+
+#### Kernel
+`int_debug_eval(str)` - Send an eval request; the str must not contain any newlines. Will respond by sending back a `if_event` message to
+the port -333 with the message name `eval_res` and the info as `{info: res}` where `res` is what ever was retrieved by the eval.
+
+`int_debug_dump_ui` - See [Debug Dump UI](./debug/dump_ui.md) for specifics.
+
+`int_debug_controller_context(bp)` - Retreive a controller's context. Sends a `if_event` to port `-333` named `debug_controller_context_res` with the payload of the controller's
+context at `bp`
+
+### Driver Spec related
+  * `if_debug_spec_assoc(base, key)` - When this message is received, the client shall return a message called `spec` containing the value
+  * `if_debug_spec_send_int_event` - This function should send the message `[0, "spec"]` to `int_event`.
+
+### Kernel spec related
+  * The function `debug_eval_spec` is in the kernel and should return 'hello'. This is called by the specs that test eval to make sure
+    that eval is working. It is never used in a message
+
+### config.yml variables
+  * `debug_attach` - See [Debug Server](../debug_server.md) for details
+
+### Debug Server
+The debug module should also provide a debug server. Details of the server are layed out in [Debug Server](../debug_server.md)

data/docs/mod/debug/dump_ui.md

@@ -0,0 +1,64 @@
+#Debug Dump UI
+The `int_debug_dump_ui` dumps the view-controller, view, and spot hierarchy. This is used in viewers like the *Seagull* client. This is a very expensive
+message as it sends back a `if_event` with the name `debug_dump_ui_res` and the address `-333` with a very large payload of many embedded hashes.
+
+##Hash linked list
+The payload returned in `int_debug_dump_ui` is a *linked* list of sorts; There is a basic type of node that looks like:
+
+```js
+Node {
+  children: [Node],
+  type: "$node_class"
+}
+```
+
+Ontop of the base node, the type defines a child class of the node:
+
+  * `vc` - View Controller
+    * `name` - The name of the view controller (human friendly)
+    * `action` - Current action name (human friendly)
+    * `ptr` - The base pointer of this view controller
+  * `view` - View
+    * `name` - The name of the view
+    * `ptr` - The pointer to the view
+  * `spot` - Spot inside a view controller's root view
+    * `name` - The name of the spot
+    * `ptr` - The pointer of this spot location
+
+Note that all view controllers have one `main` spot, this is actually just the `view` (Every view has a view controller, and vice versa).  So technically,
+the spots beyond the `main` spot are actually children of the view managed by the view controller.
+Another way to say that is that all `vc`'s will have one child and it will be a view.'
+
+Example payload:
+
+```ruby
+{
+  type: "spot",
+  name: "root",
+  ptr: 0,
+  children: [
+    {
+      name: "dashboard"
+      type: "vc",
+      action: "index",
+      view: "dashboard",
+      ptr: 2,
+      children: [
+        {
+          type: "view",
+          name: "container (main)",
+          ptr: 3
+          children: [
+            {
+              type: "spot",
+              name: "content",
+              ptr: 4,
+              children: []
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}
+```

data/docs/mod/event.md

@@ -0,0 +1,16 @@
+#Event (event.js)
+
+### Functions
+`if_event(ep, event_name, event)` - Receive an event at some object located at `ep`.  This is a platform defined opaque pointer.
+
+### Interrupts
+`int_event(ep, event_name, event)` - Send an event back to *Flok* through an event. The `ep` in this case is dependent on the sub-system. Dispatching is provided through the `evt` (event vector table). On the flok kernel, using, `reg_ivt` and `dereg_ivt` will determine what happens post int_event.  If `ep` is no longer valid, the event in ignored.
+For example, the `vc` (view controller) subsystem will receive any events sent when the `ep` is an opaque pointer to a
+./app/driver/$PLATFORM/config.yml`)
+file is used to compile only the modules into the flok kernel that the driver supports.rface controller from `ui`.
+
+### Kernel spec related
+  * `spec_event_handler(ep, event_name, event)` - This function should send the message `spec_event_handler_res(ep, event_name, event)` if called
+  * `int_spec_event_dereg` - This function should de-register 3848392 from being an event 
+
+Additionally, you should register the event pointer `3848392` to call the spec_event_handler_res.

data/docs/mod/net.md

@@ -0,0 +1,21 @@
+#Net (net.js)
+
+###Functions
+
+**@telepathy[2]**
+`"if_net_req"(verb, url, params, tp_base)` - Perform an HTTP network request with the given VERB. Assign the network request with the correct telepathy pointer.
+
+###Interrupts
+`int_net_cb(tp, success, info)` - An interrupt that a network request has completed (or failed). `success` is a bool vealue. `info` is a JSON value, `tp` is the pointer that started it
+`get_int_net_cb_spec()` - Sends [[0, 1, "get_int_net_cb_spec", int_net_cb_spec]]
+
+when successful and a string with an error message (string thats not false) when `success` is false. `tp` is the telepathy pointer passed in via `if_net_req`
+
+###Behavior, when int_net_cb is called, it should make a function request to `tp` and pass `tp`, success` and `info` to this function. Additionally, the
+kernel should set `function(tp, a, b) { int_net_cb_spec = [tp, a, b]; }` at address integer `-3209284741`.
+
+------
+
+### Overview 
+
+This driver supports network interfacing. It currently only supports HTTP requests. The `if_net_hint_cancel` can be stubbed if your platform does not support cancelling network requests, but it is best if you can attempt to do so because it will lead to more efficiency.

data/docs/mod/persist.md

@@ -0,0 +1,36 @@
+#Persist (persist.js)
+Persistance management. Storage of data, etc.  Loosely based on redis.  Refer to [redios.io](http://redis.io/commands) for more detailed
+descriptions.
+
+###Messages
+`if_per_hdel key field [field...]` - Delete one or more hash fields
+`if_per_hmget key field [field...]` - Get the value of multiple fields
+
+###Spec related
+`if_ui_spec_init` - Setup anything necessary for the spec tests, this may include adding prototype views to your hierarchy, etc.
+`if_ui_spec_views_at_spot(p)` - Sends a packet back that contains a listing of all the view pointers inside of a spot. If 0 is passed, the view pointers are from the root node. `[N(vp*), "spec", vp*]`
+`if_ui_spec_view_exists(vp)` - Checks whether or not a view still exists `[1, "spec", true]`
+`if_ui_spec_view_is_visible(vp)` - Checks whether or not a view is visible `[1, "spec", true]`
+
+#####You must be able to accept the following prototypes names:
+`spec_blank` - A blank view with no spots
+`spec_one_spot` - "A blank view with with one spot named `content` that takes up the entire view"
+`spec_two_spot` - "A blank view with with one spot named `a` and one spot named `b`.
+
+------
+
+## Overview 
+
+This driver controls two things called a **view** and a **spot**. 
+
+ 1. **View** - A **view** holds your content.
+ 2. **Spot** - Views can have blank **Spot**s where other views can be placed.
+
+## Examples
+Here is an example for the `chrome` driver of a live view built from two views.
+![](../images/view_and_spot.png)
+
+
+
+###A note on free
+If `free` is called on a view, that view is always already detached. If a *view* receives `free`, that *view* must call `free` on all of it's children before itself.

data/docs/mod/sockio.md

@@ -0,0 +1,13 @@
+#Socket.io (sockio.js)
+
+##Driver Functions
+`if_sockio_init(url, sp)` - Initialize a socketio socket with the given `url` and refer to it with `sp`.
+
+`if_sockio_fwd(sp, event_name, ep)` - A request to forward messages from a socket.io socket that represents `id` to the `ep` address as an `if_event` where the event
+name is the same as the `socket.io` `event_name` and the information is passed as the `event` field for the `if_event`. Only forward messages matching
+`event_name`.
+
+`if_sockio_send(sp, event_name, info)` - Send a socket.io message with the given message `event_name` and `info` to the socket named `id`.
+
+##Additional info
+This is functionally different than a debug server that uses the `socket_io` scheme. The debug server is required to handle socket_io by itself.

data/docs/mod/timer.md

@@ -0,0 +1,8 @@
+#Timer (timer.js)
+
+###Functions
+
+`if_timer_init(tps)` - Initiate a timer that calls `int_timer` N `tps` (ticsk per second)
+
+###Interrupts
+`int_timer` - Called by the device at the rate described in `tps`. This function lives inside the `timer` service's initialization portion.

data/docs/mod/ui.md

@@ -0,0 +1,40 @@
+#User Interface (ui.js)
+
+###Functions
+
+`if_init_view(name, info, tp_base, tp_targets)` - Create a view based on an agreed upon name for a `prototype` and pass it some `info`. Do not show the view yet.  `tp_targets` will look like `["main", "contentA", ...]` where everything after `root` is a spot.
+```js
+(main)>if_init_view('nav_container', {title: "Home"}, 333, ["root", "content"]);
+```
+
+`if_free_view(vp)` - Destroy a view with a `view pointer`.
+
+`if_attach_view(vp, p)` - A request to embed a view (`vp`) into the top of a view or spot located at `vp`|`sp` provided during `if_init_view`. If `p` is a `view pointer`, then `vp` is placed **ontop** of `p`.  If `p` is a `spot pointer`, then `vp` is placed **inside** of `p`.  If *p* is 0, then you should place this **inside** of the root view.
+
+###Spec related
+`if_ui_spec_init` - Setup anything necessary for the spec tests, this may include adding prototype views to your hierarchy, etc.
+`if_ui_spec_views_at_spot(p)` - Sends a packet back that contains a listing of all the view pointers inside of a spot. If 0 is passed, the view pointers are from the root node. `[N(vp*), "spec", vp*]`
+`if_ui_spec_view_exists(vp)` - Checks whether or not a view still exists `[1, "spec", true]`
+`if_ui_spec_view_is_visible(vp)` - Checks whether or not a view is visible `[1, "spec", true]`
+
+#####You must be able to accept the following prototypes names:
+`spec_blank` - A blank view with no spots
+`spec_one_spot` - "A blank view with with one spot named `content` that takes up the entire view"
+`spec_two_spot` - "A blank view with with one spot named `a` and one spot named `b`.
+
+------
+
+## Overview 
+
+This driver controls two things called a **view** and a **spot**. 
+
+ 1. **View** - A **view** holds your content.
+ 2. **Spot** - Views can have blank **Spot**s where other views can be placed.
+
+## Examples
+Here is an example for the `chrome` driver of a live view built from two views.
+![](../images/view_and_spot.png)
+
+###A note on free
+If `free` is called on a view, that view is always already detached. If a *view* receives `free`, that *view* must call `free` on all of it's children before itself.
+Additionally, any controllers bound to the *view* via `if_controller_init` must be destroyed as well.

data/docs/modules.md

@@ -0,0 +1,9 @@
+#Modules
+Modules define an implicit contract between a client and the flok server. The contract states what messages the client will respond to, what messages the server
+will respond to, and the semantics of those conversations.
+
+Each driver lists the modules that it is able to support. The driver implementor is responsible for implementing all the messages specified in the `./doc/mod/*.js` section.
+file is used to compile only the modules into the flok kernel that the driver supports.
+
+## Module folder in kernel
+Flok then implements it's side of the contract in the `./kern/mod/` folder. During compilation, the modules the driver supports (from the `./app/driver/$PLATFORM/config.yml`)

data/docs/project.md

@@ -0,0 +1,40 @@
+#Project
+Flok is divided up like rails.  There is the flok kernel and driver stack and then there is user-facing applications.
+
+###The flok command
+You create and build projects via the `flok` command.
+
+ * `flok new <path>` - Create a new flok project
+ * `flok build <platform>` - Build a flok project. Generates files in `./products`
+
+###Folder structure
+  * `app/`
+    * `controllers/` - All your controllers live here as `rb` files.
+  * `products/` - Autogenerated when you build
+    * `$PLATFORM/` - A folder named after the platform you selected
+      * `application_user.js` - The source for the flok application_user. Includes your application code statically linked
+      * `drivers/` - Contains the driver code needed to implement the driver side interface
+
+###application_user.js
+`application_user.js` is equivalent to the application_user build `application.js` except that it contains the users controllers statically linked (appended in *js*).
+
+###User build process
+  1. The gem is build via `build:world` using the platform given in build.
+  2. All files generated by the gem kernel and associated driver for the platform are placed in the project ./products/$PLATFORM
+  3. The controllers in `./app/controllers/*.rb` are run through the `user_compiler` in `./lib/flok/user_compiler.rb` and then saved to the projects `./products/$PLATFORM/glob/user_compiler.js`
+  4. `./products/$PLATFORM/application.js` is moved to `./products/$PLATFORM/glob/application.js`
+  5. The local project `./products/$PLATFORM/glob/application.js` and `./products/$PLATFORM/glob/user_compiler.js` are merged into `./products/$PLATFORM/glob/application_user.js.erb`.
+  6. The `erb` files is then sent to `./products/$PLATFORM/glob/application_user.js` with the below `ERB` variables allowable.
+
+####Supported variables
+  * `@debug` - Set to `true` when FLOK_ENV=DEBUG
+  * `@release` - Set to `true` when FLOK_ENV=RELEASE
+
+```js
+  //Example JS code for debug / release mode
+  <% if @debug %>
+    //JS Code for debug
+  <% else %>
+    //JS code for not debug mode
+  <% end %>
+```

data/docs/project_layout.md

@@ -1,6 +1,9 @@
 # Project layout
- * app/ - All actual pieces of the kernel code sit here.
-   * app/drivers - Parts of (a) and (b)
-     * app/drivers/iface- Generic interfaces that are suggested to be implemented.
-     * app/drivers/$PLATFORM/ - Platform specific way to implement the interface. See [platform drivers](./platform_drivers.md) for information.
-   * app/kern - The remaining part, your app, the kernel, etc. all live under here.
+ * `app/` - All actual pieces of the kernel code sit here.
+   * `app/drivers` - Parts of (a) and (b)
+     * `app/drivers/iface` - Generic interfaces that are suggested to be implemented.
+     * `app/drivers/$PLATFORM/` - Platform specific way to implement the interface. See [platform drivers](./platform_drivers.md) for information.
+   * `app/kern` - The remaining part, your app, the kernel, etc. all live under here.
+     * `app/kern/mod` - Interrupt handlers for drivers and associated code.
+     * `app/kern/macro.rb` - Contains code that is called by `./lib/flok/build.rb` to run all kernel *js* code through (except `./lib/flok/services`)
+       * This macro file provides various macros used in the kernel *and* is what controls the `DEBUG` or `RELEASE` mode ERB variables