git ssb

0+

wanderer🌟 / js-primea-hypervisor



Commit 83e76dba0665fdb89dc5636cfb77ae5150858b20

Browse Files

add initail docs

wanderer committed on 5/23/2017, 2:12:44 PM
Parent: 9b7a855ce9b773c9162179ef6cdb3c70739711f0

Files changed

docs/design.mddeleted
docs/exoInterface.mdadded
docs/hypervisor.mdadded
docs/index.mdadded
docs/port.mdadded
docs/portManager.mdadded
package.jsonchanged
docs/design.mdView
@@ -1,25 +1,0 @@
1-# Architecture
2-
3-```
4- +--------------+
5- | |
6- | Environment |
7- | |
8- +--------------+ +--------------------+
9- | | +--+
10- | +----+ Imports | |
11- | | +--------------------+ |
12- +------------+ +------------+ | | +--------------------------+
13- | | | | | +--------------------+ | | |
14- | Kernel +-------+VM Container+---------+ +------+ Sandboxed VM instance |
15- | | | | | | Imports | | | |
16- +------------+ +------------+ | +--------------------+ | +--------------------------+
17- | |
18- | +--------------------+ |
19- | | | |
20- +----+ Imports +--+
21- +--------------------+
22-
23-```
24-# Overview
25-The `Kernel` is modeled to be somewhat like [actors](https://en.wikipedia.org/wiki/Actor_model). Each Kernel/Actor is bound to a segment of code and a state tree on startup. The Kernel provides the top level API. When the kernel recieves a message from another kernel or an external source (signal) it may run that code in a VM container. The container just provides a uniform way to interact with VMs. The container is given an instance of `Evironment`. The `Evironment` contains all the ephemeral state that need for the VM container and instance. Lastly the VM container start and manages the VM instance which is assumed to be sandboxed. The Sandbox communicates to VM container via `Imports` that are exposed to it on the time of creation.
docs/exoInterface.mdView
@@ -1,0 +1,107 @@
1+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
2+
3+### Table of Contents
4+
5+- [constructor](#constructor)
6+- [start](#start)
7+- [queue](#queue)
8+- [run](#run)
9+- [wait](#wait)
10+- [incrementTicks](#incrementticks)
11+- [send](#send)
12+- [getInstance](#getinstance)
13+
14+## constructor
15+
16+[exoInterface.js:17-43](https://github.com/primea/js-primea-hypervisor/blob/9b7a855ce9b773c9162179ef6cdb3c70739711f0/exoInterface.js#L17-L43 "Source code on GitHub")
17+
18+the ExoInterface manages the varous message passing functions and provides
19+an interface for the containers to use
20+
21+**Parameters**
22+
23+- `opts` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)**
24+ - `opts.state` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)**
25+ - `opts.entryPort` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)**
26+ - `opts.parentPort` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)**
27+ - `opts.hypervisor` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)**
28+ - `opts.Container` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)**
29+
30+## start
31+
32+[exoInterface.js:49-51](https://github.com/primea/js-primea-hypervisor/blob/9b7a855ce9b773c9162179ef6cdb3c70739711f0/exoInterface.js#L49-L51 "Source code on GitHub")
33+
34+starts the container
35+
36+Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)**
37+
38+## queue
39+
40+[exoInterface.js:57-64](https://github.com/primea/js-primea-hypervisor/blob/9b7a855ce9b773c9162179ef6cdb3c70739711f0/exoInterface.js#L57-L64 "Source code on GitHub")
41+
42+adds a message to this containers message queue
43+
44+**Parameters**
45+
46+- `message` **Message**
47+
48+## run
49+
50+[exoInterface.js:88-106](https://github.com/primea/js-primea-hypervisor/blob/9b7a855ce9b773c9162179ef6cdb3c70739711f0/exoInterface.js#L88-L106 "Source code on GitHub")
51+
52+run the kernels code with a given enviroment
53+The Kernel Stores all of its state in the Environment. The Interface is used
54+to by the VM to retrive infromation from the Environment.
55+
56+**Parameters**
57+
58+- `message`
59+
60+Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)**
61+
62+## wait
63+
64+[exoInterface.js:113-127](https://github.com/primea/js-primea-hypervisor/blob/9b7a855ce9b773c9162179ef6cdb3c70739711f0/exoInterface.js#L113-L127 "Source code on GitHub")
65+
66+returns a promise that resolves once the kernel hits the threshould tick count
67+
68+**Parameters**
69+
70+- `threshold`
71+- `fromPort`
72+- `threshould` **[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** the number of ticks to wait
73+
74+Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)**
75+
76+## incrementTicks
77+
78+[exoInterface.js:133-141](https://github.com/primea/js-primea-hypervisor/blob/9b7a855ce9b773c9162179ef6cdb3c70739711f0/exoInterface.js#L133-L141 "Source code on GitHub")
79+
80+updates the number of ticks that the container has run
81+
82+**Parameters**
83+
84+- `count` **[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** the number of ticks to add
85+
86+## send
87+
88+[exoInterface.js:148-166](https://github.com/primea/js-primea-hypervisor/blob/9b7a855ce9b773c9162179ef6cdb3c70739711f0/exoInterface.js#L148-L166 "Source code on GitHub")
89+
90+sends a message to a given port
91+
92+**Parameters**
93+
94+- `portRef` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** the port
95+- `message` **Message** the message
96+
97+## getInstance
98+
99+[exoInterface.js:173-175](https://github.com/primea/js-primea-hypervisor/blob/9b7a855ce9b773c9162179ef6cdb3c70739711f0/exoInterface.js#L173-L175 "Source code on GitHub")
100+
101+gets a container instance given a port
102+
103+**Parameters**
104+
105+- `portRef` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** the port
106+
107+Returns **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)**
docs/hypervisor.mdView
@@ -1,0 +1,103 @@
1+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
2+
3+### Table of Contents
4+
5+- [constructor](#constructor)
6+- [getInstanceByPath](#getinstancebypath)
7+- [getInstanceByPort](#getinstancebyport)
8+- [wait](#wait)
9+- [createInstance](#createinstance)
10+- [createStateRoot](#createstateroot)
11+- [registerContainer](#registercontainer)
12+
13+## constructor
14+
15+[index.js:10-14](https://github.com/primea/js-primea-hypervisor/blob/9b7a855ce9b773c9162179ef6cdb3c70739711f0/index.js#L10-L14 "Source code on GitHub")
16+
17+The Hypervisor manages the container instances by instantiating them and
18+destorying them when possible. It also facilitates localating Containers
19+
20+**Parameters**
21+
22+- `dag` **Graph** an instance of [ipfs.dag](https://github.com/ipfs/interface-ipfs-core/tree/master/API/dag#dag-api)
23+
24+## getInstanceByPath
25+
26+[index.js:21-28](https://github.com/primea/js-primea-hypervisor/blob/9b7a855ce9b773c9162179ef6cdb3c70739711f0/index.js#L21-L28 "Source code on GitHub")
27+
28+get a container by its path
29+
30+**Parameters**
31+
32+- `root` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** the root container to start searching from
33+- `path` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** the path to travers
34+
35+## getInstanceByPort
36+
37+[index.js:35-46](https://github.com/primea/js-primea-hypervisor/blob/9b7a855ce9b773c9162179ef6cdb3c70739711f0/index.js#L35-L46 "Source code on GitHub")
38+
39+get a contrainer instance given its entry port and its mounting port
40+
41+**Parameters**
42+
43+- `port` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** the entry port for the container
44+- `parentPort` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** the entry port of the parent container
45+
46+## wait
47+
48+[index.js:56-63](https://github.com/primea/js-primea-hypervisor/blob/9b7a855ce9b773c9162179ef6cdb3c70739711f0/index.js#L56-L63 "Source code on GitHub")
49+
50+given a port, wait untill its source contract has reached the threshold
51+tick count
52+
53+**Parameters**
54+
55+- `port` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** the port to wait on
56+- `threshold` **[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** the number of ticks to wait before resolving
57+- `fromPort` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** the entryPort of the container requesting the
58+ wait. Used internally so that waits don't become cyclic
59+
60+## createInstance
61+
62+[index.js:73-95](https://github.com/primea/js-primea-hypervisor/blob/9b7a855ce9b773c9162179ef6cdb3c70739711f0/index.js#L73-L95 "Source code on GitHub")
63+
64+creates an instance given the container type, starting state, entry port
65+ and the parentPort
66+
67+**Parameters**
68+
69+- `type`
70+- `state`
71+- `entryPort` (optional, default `null`)
72+- `parentPort`
73+- `the` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** type of VM to load
74+- `the` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** starting state of the VM
75+- `the` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** entry port
76+- `the` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** parent port
77+
78+## createStateRoot
79+
80+[index.js:104-107](https://github.com/primea/js-primea-hypervisor/blob/9b7a855ce9b773c9162179ef6cdb3c70739711f0/index.js#L104-L107 "Source code on GitHub")
81+
82+creates a state root starting from a given container and a given number of
83+ticks
84+
85+**Parameters**
86+
87+- `container` **Container** an container instance
88+- `ticks` **[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** the number of ticks at which to create the state root
89+
90+Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)**
91+
92+## registerContainer
93+
94+[index.js:114-116](https://github.com/primea/js-primea-hypervisor/blob/9b7a855ce9b773c9162179ef6cdb3c70739711f0/index.js#L114-L116 "Source code on GitHub")
95+
96+regirsters a container with the hypervisor
97+
98+**Parameters**
99+
100+- `type`
101+- `vm`
102+- `the` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** name of the type
103+- `a` **Class** Class for instantiating the container
docs/index.mdView
@@ -1,0 +1,25 @@
1+# Architecture
2+
3+```
4+ +--------------+
5+ | |
6+ | Environment |
7+ | |
8+ +--------------+ +--------------------+
9+ | | +--+
10+ | +----+ Imports | |
11+ | | +--------------------+ |
12+ +------------+ +------------+ | | +--------------------------+
13+ | | | | | +--------------------+ | | |
14+ | Kernel +-------+VM Container+---------+ +------+ Sandboxed VM instance |
15+ | | | | | | Imports | | | |
16+ +------------+ +------------+ | +--------------------+ | +--------------------------+
17+ | |
18+ | +--------------------+ |
19+ | | | |
20+ +----+ Imports +--+
21+ +--------------------+
22+
23+```
24+# Overview
25+The `Kernel` is modeled to be somewhat like [actors](https://en.wikipedia.org/wiki/Actor_model). Each Kernel/Actor is bound to a segment of code and a state tree on startup. The Kernel provides the top level API. When the kernel recieves a message from another kernel or an external source (signal) it may run that code in a VM container. The container just provides a uniform way to interact with VMs. The container is given an instance of `Evironment`. The `Evironment` contains all the ephemeral state that need for the VM container and instance. Lastly the VM container start and manages the VM instance which is assumed to be sandboxed. The Sandbox communicates to VM container via `Imports` that are exposed to it on the time of creation.
docs/port.mdView
@@ -1,0 +1,55 @@
1+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
2+
3+### Table of Contents
4+
5+- [constructor](#constructor)
6+- [queue](#queue)
7+- [peek](#peek)
8+- [dequeue](#dequeue)
9+- [size](#size)
10+
11+## constructor
12+
13+[port.js:7-10](https://github.com/primea/js-primea-hypervisor/blob/9b7a855ce9b773c9162179ef6cdb3c70739711f0/port.js#L7-L10 "Source code on GitHub")
14+
15+a simple repsentation of a port
16+
17+**Properties**
18+
19+- `ticks` **Interger** the last know number of ticks the
20+ corrisponding container is at
21+
22+## queue
23+
24+[port.js:16-19](https://github.com/primea/js-primea-hypervisor/blob/9b7a855ce9b773c9162179ef6cdb3c70739711f0/port.js#L16-L19 "Source code on GitHub")
25+
26+queues a message on the port
27+
28+**Parameters**
29+
30+- `message`
31+- `Message`
32+
33+## peek
34+
35+[port.js:25-27](https://github.com/primea/js-primea-hypervisor/blob/9b7a855ce9b773c9162179ef6cdb3c70739711f0/port.js#L25-L27 "Source code on GitHub")
36+
37+returns the message at the front of the queue
38+
39+Returns **Message**
40+
41+## dequeue
42+
43+[port.js:33-35](https://github.com/primea/js-primea-hypervisor/blob/9b7a855ce9b773c9162179ef6cdb3c70739711f0/port.js#L33-L35 "Source code on GitHub")
44+
45+dequeue a message
46+
47+Returns **Message**
48+
49+## size
50+
51+[port.js:41-43](https://github.com/primea/js-primea-hypervisor/blob/9b7a855ce9b773c9162179ef6cdb3c70739711f0/port.js#L41-L43 "Source code on GitHub")
52+
53+returns the size of the queue
54+
55+Returns **Integer**
docs/portManager.mdView
@@ -1,0 +1,132 @@
1+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
2+
3+### Table of Contents
4+
5+- [constructor](#constructor)
6+- [start](#start)
7+- [bind](#bind)
8+- [queue](#queue)
9+- [get](#get)
10+- [delete](#delete)
11+- [isValidPort](#isvalidport)
12+- [create](#create)
13+- [wait](#wait)
14+- [getNextMessage](#getnextmessage)
15+
16+## constructor
17+
18+[portManager.js:41-44](https://github.com/primea/js-primea-hypervisor/blob/9b7a855ce9b773c9162179ef6cdb3c70739711f0/portManager.js#L41-L44 "Source code on GitHub")
19+
20+The port manager manages the the ports. This inculdes creation, deletion
21+fetching and waiting on ports
22+
23+**Parameters**
24+
25+- `opts` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)**
26+ - `opts.state` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)**
27+ - `opts.entryPort` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)**
28+ - `opts.parentPort` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)**
29+ - `opts.hypervisor` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)**
30+ - `opts.exoInterface` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)**
31+
32+## start
33+
34+[portManager.js:51-63](https://github.com/primea/js-primea-hypervisor/blob/9b7a855ce9b773c9162179ef6cdb3c70739711f0/portManager.js#L51-L63 "Source code on GitHub")
35+
36+starts the port manager. This fetchs the ports from the state and maps
37+them to thier names
38+
39+Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)**
40+
41+## bind
42+
43+[portManager.js:75-79](https://github.com/primea/js-primea-hypervisor/blob/9b7a855ce9b773c9162179ef6cdb3c70739711f0/portManager.js#L75-L79 "Source code on GitHub")
44+
45+binds a port to a name
46+
47+**Parameters**
48+
49+- `port` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** the port to bind
50+- `name` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** the name of the port
51+
52+## queue
53+
54+[portManager.js:85-87](https://github.com/primea/js-primea-hypervisor/blob/9b7a855ce9b773c9162179ef6cdb3c70739711f0/portManager.js#L85-L87 "Source code on GitHub")
55+
56+queues a message on a port
57+
58+**Parameters**
59+
60+- `message` **Message**
61+
62+## get
63+
64+[portManager.js:94-96](https://github.com/primea/js-primea-hypervisor/blob/9b7a855ce9b773c9162179ef6cdb3c70739711f0/portManager.js#L94-L96 "Source code on GitHub")
65+
66+gets a port given it's name
67+
68+**Parameters**
69+
70+- `name` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)**
71+
72+Returns **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)**
73+
74+## delete
75+
76+[portManager.js:102-106](https://github.com/primea/js-primea-hypervisor/blob/9b7a855ce9b773c9162179ef6cdb3c70739711f0/portManager.js#L102-L106 "Source code on GitHub")
77+
78+deletes a port given its name
79+
80+**Parameters**
81+
82+- `name` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)**
83+
84+## isValidPort
85+
86+[portManager.js:113-115](https://github.com/primea/js-primea-hypervisor/blob/9b7a855ce9b773c9162179ef6cdb3c70739711f0/portManager.js#L113-L115 "Source code on GitHub")
87+
88+check if a port object is still valid
89+
90+**Parameters**
91+
92+- `port` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)**
93+
94+Returns **[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)**
95+
96+## create
97+
98+[portManager.js:122-146](https://github.com/primea/js-primea-hypervisor/blob/9b7a855ce9b773c9162179ef6cdb3c70739711f0/portManager.js#L122-L146 "Source code on GitHub")
99+
100+creates a new Port given the container type
101+
102+**Parameters**
103+
104+- `type` **[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)**
105+
106+Returns **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** the newly created port
107+
108+## wait
109+
110+[portManager.js:155-167](https://github.com/primea/js-primea-hypervisor/blob/9b7a855ce9b773c9162179ef6cdb3c70739711f0/portManager.js#L155-L167 "Source code on GitHub")
111+
112+waits till all ports have reached a threshold tick count
113+
114+**Parameters**
115+
116+- `threshold` **Integer** the number of ticks to wait
117+- `fromPort` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** the port requesting the wait (optional, default `this.entryPort`)
118+- `ports` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)** the ports to wait on (optional, default `[...this._portMap]`)
119+
120+Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)**
121+
122+## getNextMessage
123+
124+[portManager.js:174-187](https://github.com/primea/js-primea-hypervisor/blob/9b7a855ce9b773c9162179ef6cdb3c70739711f0/portManager.js#L174-L187 "Source code on GitHub")
125+
126+gets the next canonical message given the an array of ports to choose from
127+
128+**Parameters**
129+
130+- `ports` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)** (optional, default `[...this._portMap]`)
131+
132+Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)**
package.jsonView
@@ -5,8 +5,13 @@
55 "scripts": {
66 "coverage": "node --harmony ./node_modules/istanbul/lib/cli.js cover ./tests/index.js",
77 "coveralls": "npm run coverage && coveralls <coverage/lcov.info",
88 "lint": "standard",
9+ "build:docs": "npm run build:docs:hypervisor && npm run build:docs:exo && npm run build:docs:ports && npm run build:docs:portManager",
10+ "build:docs:hypervisor": "documentation build ./index.js --github --shallow --sort-order source -f md > ./docs/hypervisor.md",
11+ "build:docs:exo": "documentation build ./exoInterface.js --github --shallow --sort-order source -f md > ./docs/exoInterface.md",
12+ "build:docs:ports": "documentation build ./port.js --github --shallow --sort-order source -f md > ./docs/port.md",
13+ "build:docs:portManager": "documentation build ./portManager.js --github --shallow --sort-order source -f md > ./docs/portManager.md",
914 "test": "node --harmony ./tests/index.js"
1015 },
1116 "repository": {
1217 "type": "git",
@@ -31,11 +36,12 @@
3136 "ipld-graph-builder": "1.1.5"
3237 },
3338 "devDependencies": {
3439 "coveralls": "^2.13.1",
40+ "documentation": "^4.0.0-rc.1",
3541 "ipfs": "^0.23.1",
3642 "istanbul": "^1.1.0-alpha.1",
43+ "primea-message": "0.0.1",
3744 "standard": "10.0.2",
38- "tape": "^4.5.1",
39- "primea-message": "0.0.1"
45+ "tape": "^4.5.1"
4046 }
4147 }

Built with git-ssb-web