git ssb - rebuild docs · wanderer🌟/js-primea-hypervisor@d6a84f36

Commit d6a84f3655b5a57af3ef0922429f9ef0c979c14b

rebuild docs

Signed-off-by: wanderer <mjbecze@gmail.com>

wanderer committed on 4/9/2018, 11:33:38 PM
Parent: 1f8affb407f9413e9af400e3cc7408ece8274347

Files changed

README.md	changed
actor.js	changed
docs/actor.md	changed
docs/hypervisor.md	changed
docs/index.md	changed
index.js	changed
package.json	changed

README.mdView
		@@ -10,16 +10,56 @@
10	10
11	11	# INSTALL
12	12	clone and run `npm install`
13	13
	14	+# USAGE
	15	+```javascript
14	16
15		-# TESTS
16		-`npm test`
	17	+const Hypervisor = require('primea-hypervisor')
	18	+const {Message, FunctionRef} = require('primea-objects')
	19	+const WasmContainer = require('primea-wasm-container')
17	20
	21	+// setup presistant state
	22	+const level = require('level-browserify')
	23	+const RadixTree = require('dfinity-radix-tree')
	24	+const db = level(`${__dirname}/db`)
	25	+const tree = new RadixTree({db})
18	26
	27	+const hypervisor = new Hypervisor({tree, containers: [WasmContainer]})
	28	+
	29	+const wasm // a webassembly binary with an exported function named "main"
	30	+
	31	+// create an actor with a webassembly container
	32	+const {module} = hypervisor.createActor(WasmContainer.typeId, wasm)
	33	+
	34	+// create message to send to the actor that was just created
	35	+const message = new Message({
	36	+ funcRef: module.getFuncRef('main'),
	37	+ funcArguments: [new FunctionRef({
	38	+ actorID: egress.id,
	39	+ params: ['data']
	40	+ })]
	41	+}).on('execution:error', e => console.error(e))
	42	+
	43	+hypervisor.send(message)
	44	+
	45	+// write everything to the db can create a merkle tree with a single state root
	46	+const sr = await hypervisor.createStateRoot()
	47	+console.log('state root:', sr.toString('hex'))
	48	+```
	49	+
19	50	# API
20	51	[./docs](./docs/index.md)
21	52
	53	+# DESIGN
	54	+Primea is an [actor based system](https://en.wikipedia.org/wiki/Actor_model) with [capabilities](https://en.wikipedia.org/wiki/Capability-based_security).
	55	+Its high level goals are
	56	+
	57	+* Performant IPC
	58	+* Extensible, allowing for upgrades and customization
	59	+* Interoperability with existing codebases
	60	+* Deterministic execution
	61	+
22	62	# LICENSE
23	63	[MPL-2.0][LICENSE]
24	64
25	65	[LICENSE]: https://tldrlegal.com/license/mozilla-public-license-2.0-(mpl-2)

actor.jsView
		@@ -5,12 +5,15 @@
5	5	/**
6	6	* the Actor manages the varous message passing functions and provides
7	7	* an interface for the containers to use
8	8	* @param {Object} opts
9		- * @param {Object} opts.id - the UUID of the Actor
	9	+ * @param {ID} opts.id - the UUID of the Actor
10	10	* @param {Object} opts.state - the state of the container
	11	+ * @param {Object} opts.storage - the actor's persistant storage
11	12	* @param {Object} opts.hypervisor - the instance of the hypervisor
12		- * @param {Object} opts.container - the container constuctor and argments
	13	+ * @param {Number} opts.nonce
	14	+ * @param {Number} opts.type - the container type
	15	+ * @param {Function} opts.container - the container constuctor and argments
13	16	*/
14	17	constructor (opts) {
15	18	Object.assign(this, opts)
16	19

docs/actor.mdView
		@@ -1,84 +1,127 @@
1	1	<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
2	2
3	3	### Table of Contents
4	4
5		-- [constructor](#constructor)
6		-- [shutdown](#shutdown)
7		-- [startup](#startup)
8		-- [runMessage](#runmessage)
9		-- [incrementTicks](#incrementticks)
10		-- [createActor](#createactor)
11		-- [send](#send)
	5	+- [constructor][1]
	6	+- [shutdown][2]
	7	+- [startup][3]
	8	+- [runMessage][4]
	9	+- [incrementTicks][5]
	10	+- [createActor][6]
	11	+- [send][7]
12	12
13	13	## constructor
14	14
15		-[actor.js:11-18](https://github.com/dfinity/js-primea/blob/21960d62467278cd5659e2eb5f80cc6ddd87e663/actor.js#L11-L18 "Source code on GitHub")
	15	+[actor.js:17-26][8]
16	16
17	17	the Actor manages the varous message passing functions and provides
18	18	an interface for the containers to use
19	19
20	20	Parameters
21	21
22		-- `opts` [Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)
23		- - `opts.id` [Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object) the UUID of the Actor
24		- - `opts.state` [Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object) the state of the container
25		- - `opts.hypervisor` [Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object) the instance of the hypervisor
26		- - `opts.container` [Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object) the container constuctor and argments
	22	+- `opts` [Object][9]
	23	+ - `opts.id` ID the UUID of the Actor
	24	+ - `opts.state` [Object][9] the state of the container
	25	+ - `opts.storage` [Object][9] the actor's persistant storage
	26	+ - `opts.hypervisor` [Object][9] the instance of the hypervisor
	27	+ - `opts.nonce` [Number][10]
	28	+ - `opts.type` [Number][10] the container type
	29	+ - `opts.container` [Function][11] the container constuctor and argments
27	30
28	31	## shutdown
29	32
30		-[actor.js:23-29](https://github.com/dfinity/js-primea/blob/21960d62467278cd5659e2eb5f80cc6ddd87e663/actor.js#L23-L29 "Source code on GitHub")
	33	+[actor.js:31-35][12]
31	34
32	35	Runs the shutdown routine for the actor
33	36
34	37	## startup
35	38
36		-[actor.js:34-36](https://github.com/dfinity/js-primea/blob/21960d62467278cd5659e2eb5f80cc6ddd87e663/actor.js#L34-L36 "Source code on GitHub")
	39	+[actor.js:40-42][13]
37	40
38	41	Runs the startup routine for the actor
39	42
40	43	## runMessage
41	44
42		-[actor.js:44-56](https://github.com/dfinity/js-primea/blob/21960d62467278cd5659e2eb5f80cc6ddd87e663/actor.js#L44-L56 "Source code on GitHub")
	45	+[actor.js:50-61][14]
43	46
44	47	run the Actor with a given message
45	48
46	49	Parameters
47	50
48		-- `message` [object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object) the message to run
49		-- `method` [String](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) which method to run
	51	+- `message` [object][9] the message to run
	52	+- `method` [String][15] which method to run
50	53
51		-Returns [Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)
	54	+Returns [Promise][16]
52	55
53	56	## incrementTicks
54	57
55		-[actor.js:62-64](https://github.com/dfinity/js-primea/blob/21960d62467278cd5659e2eb5f80cc6ddd87e663/actor.js#L62-L64 "Source code on GitHub")
	58	+[actor.js:67-73][17]
56	59
57	60	updates the number of ticks that the actor has run
58	61
59	62	Parameters
60	63
61		-- `count` [Number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number) the number of ticks to add
	64	+- `count` [Number][10] the number of ticks to add
62	65
63	66	## createActor
64	67
65		-[actor.js:71-74](https://github.com/dfinity/js-primea/blob/21960d62467278cd5659e2eb5f80cc6ddd87e663/actor.js#L71-L74 "Source code on GitHub")
	68	+[actor.js:80-83][18]
66	69
67	70	creates an actor
68	71
69	72	Parameters
70	73
71	74	- `type` Integer the type id for the container
72	75	- `code`
73		-- `message` [Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object) an intial [message](https://github.com/primea/js-primea-message) to send newly created actor
	76	+- `message` [Object][9] an intial [message][19] to send newly created actor
74	77
75	78	## send
76	79
77		-[actor.js:91-96](https://github.com/dfinity/js-primea/blob/21960d62467278cd5659e2eb5f80cc6ddd87e663/actor.js#L91-L96 "Source code on GitHub")
	80	+[actor.js:100-105][20]
78	81
79	82	sends a message to a given port
80	83
81	84	Parameters
82	85
83	86	- `message` Message the message
84		-- `portRef` [Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object) the port
	87	+- `portRef` [Object][9] the port
	88	+
	89	+[1]: #constructor
	90	+
	91	+[2]: #shutdown
	92	+
	93	+[3]: #startup
	94	+
	95	+[4]: #runmessage
	96	+
	97	+[5]: #incrementticks
	98	+
	99	+[6]: #createactor
	100	+
	101	+[7]: #send
	102	+
	103	+[8]: https://github.com/dfinity/js-primea/blob/1f8affb407f9413e9af400e3cc7408ece8274347/actor.js#L17-L26 "Source code on GitHub"
	104	+
	105	+[9]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
	106	+
	107	+[10]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number
	108	+
	109	+[11]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function
	110	+
	111	+[12]: https://github.com/dfinity/js-primea/blob/1f8affb407f9413e9af400e3cc7408ece8274347/actor.js#L31-L35 "Source code on GitHub"
	112	+
	113	+[13]: https://github.com/dfinity/js-primea/blob/1f8affb407f9413e9af400e3cc7408ece8274347/actor.js#L40-L42 "Source code on GitHub"
	114	+
	115	+[14]: https://github.com/dfinity/js-primea/blob/1f8affb407f9413e9af400e3cc7408ece8274347/actor.js#L50-L61 "Source code on GitHub"
	116	+
	117	+[15]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
	118	+
	119	+[16]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise
	120	+
	121	+[17]: https://github.com/dfinity/js-primea/blob/1f8affb407f9413e9af400e3cc7408ece8274347/actor.js#L67-L73 "Source code on GitHub"
	122	+
	123	+[18]: https://github.com/dfinity/js-primea/blob/1f8affb407f9413e9af400e3cc7408ece8274347/actor.js#L80-L83 "Source code on GitHub"
	124	+
	125	+[19]: https://github.com/primea/js-primea-message
	126	+
	127	+[20]: https://github.com/dfinity/js-primea/blob/1f8affb407f9413e9af400e3cc7408ece8274347/actor.js#L100-L105 "Source code on GitHub"

docs/hypervisor.mdView
		@@ -1,73 +1,160 @@
1	1	<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
2	2
3	3	### Table of Contents
4	4
5		-- [constructor](#constructor)
6		-- [send](#send)
7		-- [createActor](#createactor)
8		-- [createStateRoot](#createstateroot)
9		-- [registerContainer](#registercontainer)
	5	+- [constructor][1]
	6	+- [send][2]
	7	+- [loadActor][3]
	8	+- [createActor][4]
	9	+- [createStateRoot][5]
	10	+- [setStateRoot][6]
	11	+- [registerContainer][7]
	12	+- [registerDriver][8]
10	13
11	14	## constructor
12	15
13		-[index.js:12-17](https://github.com/dfinity/js-primea/blob/21960d62467278cd5659e2eb5f80cc6ddd87e663/index.js#L12-L17 "Source code on GitHub")
	16	+[index.js:18-27][9]
14	17
15	18	The Hypervisor manages the container instances by instantiating them and
16	19	destorying them when possible. It also facilitates localating Containers
17	20
18	21	Parameters
19	22
20		-- `tree` Tree a [radix tree](https://github.com/dfinity/js-dfinity-radix-tree) to store the state
21		-- `nonce` (optional, default `0`)
	23	+- `opts` [Object][10]
	24	+ - `opts.tree` [Object][10] a [radix tree][11] to store the state
	25	+ - `opts.container` [Array][12] an array of containers to regester
	26	+ - `opts.drivers` [Array][12] an array of drivers to install
	27	+ - `opts.meter` [boolean][13] whether to meter gas or not (optional, default `true`)
22	28
23	29	## send
24	30
25		-[index.js:25-30](https://github.com/dfinity/js-primea/blob/21960d62467278cd5659e2eb5f80cc6ddd87e663/index.js#L25-L30 "Source code on GitHub")
	31	+[index.js:34-39][14]
26	32
27		-sends a message
	33	+sends a message(s). If an array of message is given the all the messages will be sent at once
28	34
29	35	Parameters
30	36
31	37	- `messages`
32		-- `cap` [Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object) the capabilitly used to send the message
33		-- `message` [Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object) the [message](https://github.com/primea/js-primea-message) to send
	38	+- `message` [Object][10] the [message][15] to send
34	39
35		-Returns [Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise) a promise that resolves once the receiving container is loaded
	40	+Returns [Promise][16] a promise that resolves once the receiving container is loaded
36	41
	42	+## loadActor
	43	+
	44	+[index.js:46-70][17]
	45	+
	46	+loads an actor from the tree given its id
	47	+
	48	+Parameters
	49	+
	50	+- `id` ID
	51	+
	52	+Returns [Promise][16]<Actor>
	53	+
37	54	## createActor
38	55
39		-[index.js:65-83](https://github.com/dfinity/js-primea/blob/21960d62467278cd5659e2eb5f80cc6ddd87e663/index.js#L65-L83 "Source code on GitHub")
	56	+[index.js:78-102][18]
40	57
41	58	creates an instance of an Actor
42	59
43	60	Parameters
44	61
45	62	- `type` Integer the type id for the container
46	63	- `code`
47		-- `id` [Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object) the id for the actor (optional, default `{nonce:this.nonce++,parent:null}`)
48		-- `message` [Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object) an intial [message](https://github.com/primea/js-primea-message) to send newly created actor
	64	+- `id` [Object][10] the id for the actor (optional, default `{nonce:this.nonce++,parent:null}`)
	65	+- `message` [Object][10] an intial [message][15] to send newly created actor
49	66
50	67	## createStateRoot
51	68
52		-[index.js:98-104](https://github.com/dfinity/js-primea/blob/21960d62467278cd5659e2eb5f80cc6ddd87e663/index.js#L98-L104 "Source code on GitHub")
	69	+[index.js:116-124][19]
53	70
54	71	creates a state root starting from a given container and a given number of
55	72	ticks
56	73
57	74	Parameters
58	75
59		-- `ticks` [Number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number) the number of ticks at which to create the state root
	76	+- `ticks` [Number][20] the number of ticks at which to create the state root
60	77
61		-Returns [Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)
	78	+Returns [Promise][16]
62	79
	80	+## setStateRoot
	81	+
	82	+[index.js:131-135][21]
	83	+
	84	+set the state root. The promise must resolve before creating or sending any more messages to the hypervisor
	85	+
	86	+Parameters
	87	+
	88	+- `stateRoot` [Buffer][22]
	89	+
	90	+Returns [Promise][16]
	91	+
63	92	## registerContainer
64	93
65		-[index.js:112-114](https://github.com/dfinity/js-primea/blob/21960d62467278cd5659e2eb5f80cc6ddd87e663/index.js#L112-L114 "Source code on GitHub")
	94	+[index.js:141-143][23]
66	95
67		-regirsters a container with the hypervisor
	96	+regesters a container with the hypervisor
68	97
69	98	Parameters
70	99
71		-- `Constructor` Class a Class for instantiating the container
72		-- `args` any any args that the contructor takes
73		-- `typeId` Integer the container's type identification ID
	100	+- `Constructor` [Function][24] the container's constuctor
	101	+
	102	+## registerDriver
	103	+
	104	+[index.js:149-151][25]
	105	+
	106	+register a driver with the hypervisor
	107	+
	108	+Parameters
	109	+
	110	+- `driver` driver
	111	+
	112	+[1]: #constructor
	113	+
	114	+[2]: #send
	115	+
	116	+[3]: #loadactor
	117	+
	118	+[4]: #createactor
	119	+
	120	+[5]: #createstateroot
	121	+
	122	+[6]: #setstateroot
	123	+
	124	+[7]: #registercontainer
	125	+
	126	+[8]: #registerdriver
	127	+
	128	+[9]: https://github.com/dfinity/js-primea/blob/1f8affb407f9413e9af400e3cc7408ece8274347/index.js#L18-L27 "Source code on GitHub"
	129	+
	130	+[10]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
	131	+
	132	+[11]: https://github.com/dfinity/js-dfinity-radix-tree
	133	+
	134	+[12]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array
	135	+
	136	+[13]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean
	137	+
	138	+[14]: https://github.com/dfinity/js-primea/blob/1f8affb407f9413e9af400e3cc7408ece8274347/index.js#L34-L39 "Source code on GitHub"
	139	+
	140	+[15]: https://github.com/primea/js-primea-message
	141	+
	142	+[16]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise
	143	+
	144	+[17]: https://github.com/dfinity/js-primea/blob/1f8affb407f9413e9af400e3cc7408ece8274347/index.js#L46-L70 "Source code on GitHub"
	145	+
	146	+[18]: https://github.com/dfinity/js-primea/blob/1f8affb407f9413e9af400e3cc7408ece8274347/index.js#L78-L102 "Source code on GitHub"
	147	+
	148	+[19]: https://github.com/dfinity/js-primea/blob/1f8affb407f9413e9af400e3cc7408ece8274347/index.js#L116-L124 "Source code on GitHub"
	149	+
	150	+[20]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number
	151	+
	152	+[21]: https://github.com/dfinity/js-primea/blob/1f8affb407f9413e9af400e3cc7408ece8274347/index.js#L131-L135 "Source code on GitHub"
	153	+
	154	+[22]: https://nodejs.org/api/buffer.html
	155	+
	156	+[23]: https://github.com/dfinity/js-primea/blob/1f8affb407f9413e9af400e3cc7408ece8274347/index.js#L141-L143 "Source code on GitHub"
	157	+
	158	+[24]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function
	159	+
	160	+[25]: https://github.com/dfinity/js-primea/blob/1f8affb407f9413e9af400e3cc7408ece8274347/index.js#L149-L151 "Source code on GitHub"

docs/index.mdView
		@@ -1,6 +1,3 @@
1	1	# API
2	2	- [Hypervisor](./hypervisor.md)
3	3	- [Actor](./actor.md)
4		-
5		-## Internal APIs
6		-- [Scheduler](./scheduler.md)

index.jsView
		@@ -26,9 +26,9 @@
26	26	(opts.drivers \|\| []).forEach(driver => this.registerDriver(driver))
27	27	}
28	28
29	29	/**
30		- * sends a message
	30	+ * sends a message(s). If an array of message is given the all the messages will be sent at once
31	31	* @param {Object} message - the [message](https://github.com/primea/js-primea-message) to send
32	32	* @returns {Promise} a promise that resolves once the receiving container is loaded
33	33	*/
34	34	send (messages) {
		@@ -79,9 +79,9 @@
79	79	const Container = this._containerTypes[type]
80	80	const encoded = encodedID(id)
81	81	id = this._hash(encoded)
82	82	id = new ID(id)
83		- const module = Container.onCreation(code, id, this.tree)
	83	+ const module = Container.onCreation(code, id)
84	84	const metaData = [type, 0]
85	85
86	86	// save the container in the state
87	87	this.tree.set(id.id, metaData).then(node => {
		@@ -123,26 +123,30 @@
123	123	return this.tree.flush()
124	124	}
125	125
126	126	/**
127		- * set the state root
	127	+ * set the state root. The promise must resolve before creating or sending any more messages to the hypervisor
	128	+ * @param {Buffer} stateRoot
	129	+ * @return {Promise}
128	130	*/
129	131	async setStateRoot (stateRoot) {
130	132	this.tree.root = stateRoot
131	133	const node = await this.tree.get(Buffer.from([0]))
132	134	this.nonce = node.value
133	135	}
134	136
135	137	/**
136		- * regirsters a container with the hypervisor
137		- * @param {Class} Constructor - a Class for instantiating the container
138		- * @param {*} args - any args that the contructor takes
139		- * @param {Integer} typeId - the container's type identification ID
	138	+ * regesters a container with the hypervisor
	139	+ * @param {Function} Constructor - the container's constuctor
140	140	*/
141	141	registerContainer (Constructor) {
142	142	this._containerTypes[Constructor.typeId] = Constructor
143	143	}
144	144
	145	+ /**
	146	+ * register a driver with the hypervisor
	147	+ * @param {driver} driver
	148	+ */
145	149	registerDriver (driver) {
146	150	this.scheduler.drivers.set(driver.id.toString(), driver)
147	151	}
148	152	}

package.jsonView
		@@ -5,12 +5,11 @@
5	5	"scripts": {
6	6	"coveralls": "npm run coverage && nyc report --reporter=text-lcov \| coveralls",
7	7	"coverage": "nyc npm test",
8	8	"lint": "standard",
9		- "build:docs": "npm run build:docs:hypervisor && npm run build:docs:actor && npm run build:docs:scheduler",
	9	+ "build:docs": "npm run build:docs:hypervisor && npm run build:docs:actor",
10	10	"build:docs:hypervisor": "documentation build ./index.js --github --shallow --sort-order source -f md > ./docs/hypervisor.md",
11	11	"build:docs:actor": "documentation build ./actor.js --github --shallow --sort-order source -f md > ./docs/actor.md",
12		- "build:docs:scheduler": "documentation build ./scheduler.js --github --shallow --sort-order source -f md > ./docs/scheduler.md",
13	12	"test": "node ./tests/index.js",
14	13	"test:wasm": "node ./tests/wasmContainer.js"
15	14	},
16	15	"repository": {

Built with git-ssb-web

wanderer🌟 / js-primea-hypervisor

Commit d6a84f3655b5a57af3ef0922429f9ef0c979c14b

rebuild docs

Files changed