git ssb - added example · wanderer🌟/js-primea-hypervisor@74ccd6e3

Commit 74ccd6e33a63430ec22a6fcbfd0fd40f10c349c5

added example

wanderer committed on 6/29/2017, 7:18:49 AM
Parent: 317d79e49cb56dd81cb9c94072cd24ad6a825757

Files changed

docs/hypervisor.md	changed
docs/kernel.md	changed
docs/portManager.md	changed
kernel.js	changed
examples/index.js	added

docs/hypervisor.mdView
		@@ -8,13 +8,12 @@
8	8	- [getInstance](#getinstance)
9	9	- [createInstance](#createinstance)
10	10	- [createStateRoot](#createstateroot)
11	11	- [registerContainer](#registercontainer)
12		-- [getHashFromObj](#gethashfromobj)
13	12
14	13	## constructor
15	14
16		-[index.js:16-22](https://github.com/primea/js-primea-hypervisor/blob/b507f49239a73767abbee979b4e637a6ca469764/index.js#L16-L22 "Source code on GitHub")
	15	+[index.js:16-22](https://github.com/primea/js-primea-hypervisor/blob/317d79e49cb56dd81cb9c94072cd24ad6a825757/index.js#L16-L22 "Source code on GitHub")
17	16
18	17	The Hypervisor manages the container instances by instantiating them and
19	18	destorying them when possible. It also facilitates localating Containers
20	19
		@@ -24,9 +23,9 @@
24	23	- `state` [object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) the starting state (optional, default `{}`)
25	24
26	25	## addNodeToCheck
27	26
28		-[index.js:28-30](https://github.com/primea/js-primea-hypervisor/blob/b507f49239a73767abbee979b4e637a6ca469764/index.js#L28-L30 "Source code on GitHub")
	27	+[index.js:28-30](https://github.com/primea/js-primea-hypervisor/blob/317d79e49cb56dd81cb9c94072cd24ad6a825757/index.js#L28-L30 "Source code on GitHub")
29	28
30	29	add a potaintail node in the state graph to check for garbage collection
31	30
32	31	Parameters
		@@ -34,9 +33,9 @@
34	33	- `id` [string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)
35	34
36	35	## getDestPort
37	36
38		-[index.js:37-43](https://github.com/primea/js-primea-hypervisor/blob/b507f49239a73767abbee979b4e637a6ca469764/index.js#L37-L43 "Source code on GitHub")
	37	+[index.js:37-43](https://github.com/primea/js-primea-hypervisor/blob/317d79e49cb56dd81cb9c94072cd24ad6a825757/index.js#L37-L43 "Source code on GitHub")
39	38
40	39	given a port, this finds the corridsponeding endpoint port of the channel
41	40
42	41	Parameters
		@@ -46,9 +45,9 @@
46	45	Returns [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)
47	46
48	47	## getInstance
49	48
50		-[index.js:68-78](https://github.com/primea/js-primea-hypervisor/blob/b507f49239a73767abbee979b4e637a6ca469764/index.js#L68-L78 "Source code on GitHub")
	49	+[index.js:73-83](https://github.com/primea/js-primea-hypervisor/blob/317d79e49cb56dd81cb9c94072cd24ad6a825757/index.js#L73-L83 "Source code on GitHub")
51	50
52	51	gets an existsing container instances
53	52
54	53	Parameters
		@@ -58,9 +57,9 @@
58	57	Returns [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)
59	58
60	59	## createInstance
61	60
62		-[index.js:90-114](https://github.com/primea/js-primea-hypervisor/blob/b507f49239a73767abbee979b4e637a6ca469764/index.js#L90-L114 "Source code on GitHub")
	61	+[index.js:95-119](https://github.com/primea/js-primea-hypervisor/blob/317d79e49cb56dd81cb9c94072cd24ad6a825757/index.js#L95-L119 "Source code on GitHub")
63	62
64	63	creates an new container instances and save it in the state
65	64
66	65	Parameters
		@@ -75,9 +74,9 @@
75	74	Returns [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)
76	75
77	76	## createStateRoot
78	77
79		-[index.js:122-129](https://github.com/primea/js-primea-hypervisor/blob/b507f49239a73767abbee979b4e637a6ca469764/index.js#L122-L129 "Source code on GitHub")
	78	+[index.js:127-134](https://github.com/primea/js-primea-hypervisor/blob/317d79e49cb56dd81cb9c94072cd24ad6a825757/index.js#L127-L134 "Source code on GitHub")
80	79
81	80	creates a state root starting from a given container and a given number of
82	81	ticks
83	82
		@@ -88,25 +87,13 @@
88	87	Returns [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)
89	88
90	89	## registerContainer
91	90
92		-[index.js:137-142](https://github.com/primea/js-primea-hypervisor/blob/b507f49239a73767abbee979b4e637a6ca469764/index.js#L137-L142 "Source code on GitHub")
	91	+[index.js:142-147](https://github.com/primea/js-primea-hypervisor/blob/317d79e49cb56dd81cb9c94072cd24ad6a825757/index.js#L142-L147 "Source code on GitHub")
93	92
94	93	regirsters a container with the hypervisor
95	94
96	95	Parameters
97	96
98	97	- `type` [String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String) the name of the type
99	98	- `Constructor` Class a Class for instantiating the container
100	99	- `args` any any args that the contructor takes
101		-
102		-## getHashFromObj
103		-
104		-[index.js:149-151](https://github.com/primea/js-primea-hypervisor/blob/b507f49239a73767abbee979b4e637a6ca469764/index.js#L149-L151 "Source code on GitHub")
105		-
106		-get a hash from a POJO
107		-
108		-Parameters
109		-
110		-- `obj` [object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)
111		-
112		-Returns [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)

docs/kernel.mdView
		@@ -10,24 +10,24 @@
10	10	- [send](#send)
11	11
12	12	## constructor
13	13
14		-[kernel.js:15-28](https://github.com/primea/js-primea-hypervisor/blob/b507f49239a73767abbee979b4e637a6ca469764/kernel.js#L15-L28 "Source code on GitHub")
	14	+[kernel.js:15-28](https://github.com/primea/js-primea-hypervisor/blob/317d79e49cb56dd81cb9c94072cd24ad6a825757/kernel.js#L15-L28 "Source code on GitHub")
15	15
16		-the ExoInterface manages the varous message passing functions and provides
	16	+the Kernel manages the varous message passing functions and provides
17	17	an interface for the containers to use
18	18
19	19	Parameters
20	20
21	21	- `opts` [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)
22		- - `opts.id` [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)
23		- - `opts.state` [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)
	22	+ - `opts.id` [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) the UUID of the Kernel
	23	+ - `opts.state` [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) the state of the container
24	24	- `opts.hypervisor` [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)
25		- - `opts.Container` [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)
	25	+ - `opts.container` [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) the container constuctor and argments
26	26
27	27	## queue
28	28
29		-[kernel.js:35-48](https://github.com/primea/js-primea-hypervisor/blob/b507f49239a73767abbee979b4e637a6ca469764/kernel.js#L35-L48 "Source code on GitHub")
	29	+[kernel.js:35-48](https://github.com/primea/js-primea-hypervisor/blob/317d79e49cb56dd81cb9c94072cd24ad6a825757/kernel.js#L35-L48 "Source code on GitHub")
30	30
31	31	adds a message to this containers message queue
32	32
33	33	Parameters
		@@ -36,24 +36,22 @@
36	36	- `message` [object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)
37	37
38	38	## run
39	39
40		-[kernel.js:78-98](https://github.com/primea/js-primea-hypervisor/blob/b507f49239a73767abbee979b4e637a6ca469764/kernel.js#L78-L98 "Source code on GitHub")
	40	+[kernel.js:78-98](https://github.com/primea/js-primea-hypervisor/blob/317d79e49cb56dd81cb9c94072cd24ad6a825757/kernel.js#L78-L98 "Source code on GitHub")
41	41
42	42	run the kernels code with a given enviroment
43		-The Kernel Stores all of its state in the Environment. The Interface is used
44		-to by the VM to retrive infromation from the Environment.
45	43
46	44	Parameters
47	45
48		-- `message`
49		-- `init` (optional, default `false`)
	46	+- `message` [object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) the message to run
	47	+- `init` [boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean) whether or not to run the intialization routine (optional, default `false`)
50	48
51	49	Returns [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)
52	50
53	51	## incrementTicks
54	52
55		-[kernel.js:104-107](https://github.com/primea/js-primea-hypervisor/blob/b507f49239a73767abbee979b4e637a6ca469764/kernel.js#L104-L107 "Source code on GitHub")
	53	+[kernel.js:104-107](https://github.com/primea/js-primea-hypervisor/blob/317d79e49cb56dd81cb9c94072cd24ad6a825757/kernel.js#L104-L107 "Source code on GitHub")
56	54
57	55	updates the number of ticks that the container has run
58	56
59	57	Parameters
		@@ -61,9 +59,9 @@
61	59	- `count` [Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number) the number of ticks to add
62	60
63	61	## createMessage
64	62
65		-[kernel.js:113-121](https://github.com/primea/js-primea-hypervisor/blob/b507f49239a73767abbee979b4e637a6ca469764/kernel.js#L113-L121 "Source code on GitHub")
	63	+[kernel.js:113-121](https://github.com/primea/js-primea-hypervisor/blob/317d79e49cb56dd81cb9c94072cd24ad6a825757/kernel.js#L113-L121 "Source code on GitHub")
66	64
67	65	creates a new message
68	66
69	67	Parameters
		@@ -72,9 +70,9 @@
72	70	- `data` any
73	71
74	72	## send
75	73
76		-[kernel.js:128-145](https://github.com/primea/js-primea-hypervisor/blob/b507f49239a73767abbee979b4e637a6ca469764/kernel.js#L128-L145 "Source code on GitHub")
	74	+[kernel.js:128-145](https://github.com/primea/js-primea-hypervisor/blob/317d79e49cb56dd81cb9c94072cd24ad6a825757/kernel.js#L128-L145 "Source code on GitHub")
77	75
78	76	sends a message to a given port
79	77
80	78	Parameters

docs/portManager.mdView
		@@ -15,9 +15,9 @@
15	15	- [getNextMessage](#getnextmessage)
16	16
17	17	## constructor
18	18
19		-[portManager.js:33-44](https://github.com/primea/js-primea-hypervisor/blob/b507f49239a73767abbee979b4e637a6ca469764/portManager.js#L33-L44 "Source code on GitHub")
	19	+[portManager.js:33-44](https://github.com/primea/js-primea-hypervisor/blob/317d79e49cb56dd81cb9c94072cd24ad6a825757/portManager.js#L33-L44 "Source code on GitHub")
20	20
21	21	The port manager manages the the ports. This inculdes creation, deletion
22	22	fetching and waiting on ports
23	23
		@@ -29,9 +29,9 @@
29	29	- `opts.exoInterface` [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)
30	30
31	31	## bind
32	32
33		-[portManager.js:51-73](https://github.com/primea/js-primea-hypervisor/blob/b507f49239a73767abbee979b4e637a6ca469764/portManager.js#L51-L73 "Source code on GitHub")
	33	+[portManager.js:51-73](https://github.com/primea/js-primea-hypervisor/blob/317d79e49cb56dd81cb9c94072cd24ad6a825757/portManager.js#L51-L73 "Source code on GitHub")
34	34
35	35	binds a port to a name
36	36
37	37	Parameters
		@@ -40,9 +40,9 @@
40	40	- `port` [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) the port to bind
41	41
42	42	## unbind
43	43
44		-[portManager.js:80-92](https://github.com/primea/js-primea-hypervisor/blob/b507f49239a73767abbee979b4e637a6ca469764/portManager.js#L80-L92 "Source code on GitHub")
	44	+[portManager.js:80-92](https://github.com/primea/js-primea-hypervisor/blob/317d79e49cb56dd81cb9c94072cd24ad6a825757/portManager.js#L80-L92 "Source code on GitHub")
45	45
46	46	unbinds a port given its name
47	47
48	48	Parameters
		@@ -52,9 +52,9 @@
52	52	Returns [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)
53	53
54	54	## delete
55	55
56		-[portManager.js:98-102](https://github.com/primea/js-primea-hypervisor/blob/b507f49239a73767abbee979b4e637a6ca469764/portManager.js#L98-L102 "Source code on GitHub")
	56	+[portManager.js:98-102](https://github.com/primea/js-primea-hypervisor/blob/317d79e49cb56dd81cb9c94072cd24ad6a825757/portManager.js#L98-L102 "Source code on GitHub")
57	57
58	58	delete an port given the name it is bound to
59	59
60	60	Parameters
		@@ -62,15 +62,15 @@
62	62	- `name` [string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)
63	63
64	64	## clearUnboundedPorts
65	65
66		-[portManager.js:112-120](https://github.com/primea/js-primea-hypervisor/blob/b507f49239a73767abbee979b4e637a6ca469764/portManager.js#L112-L120 "Source code on GitHub")
	66	+[portManager.js:112-120](https://github.com/primea/js-primea-hypervisor/blob/317d79e49cb56dd81cb9c94072cd24ad6a825757/portManager.js#L112-L120 "Source code on GitHub")
67	67
68	68	clears any unbounded ports referances
69	69
70	70	## isBound
71	71
72		-[portManager.js:127-129](https://github.com/primea/js-primea-hypervisor/blob/b507f49239a73767abbee979b4e637a6ca469764/portManager.js#L127-L129 "Source code on GitHub")
	72	+[portManager.js:127-129](https://github.com/primea/js-primea-hypervisor/blob/317d79e49cb56dd81cb9c94072cd24ad6a825757/portManager.js#L127-L129 "Source code on GitHub")
73	73
74	74	check if a port object is still valid
75	75
76	76	Parameters
		@@ -80,9 +80,9 @@
80	80	Returns [Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)
81	81
82	82	## queue
83	83
84		-[portManager.js:135-157](https://github.com/primea/js-primea-hypervisor/blob/b507f49239a73767abbee979b4e637a6ca469764/portManager.js#L135-L157 "Source code on GitHub")
	84	+[portManager.js:135-157](https://github.com/primea/js-primea-hypervisor/blob/317d79e49cb56dd81cb9c94072cd24ad6a825757/portManager.js#L135-L157 "Source code on GitHub")
85	85
86	86	queues a message on a port
87	87
88	88	Parameters
		@@ -91,9 +91,9 @@
91	91	- `message` Message
92	92
93	93	## get
94	94
95		-[portManager.js:164-166](https://github.com/primea/js-primea-hypervisor/blob/b507f49239a73767abbee979b4e637a6ca469764/portManager.js#L164-L166 "Source code on GitHub")
	95	+[portManager.js:164-166](https://github.com/primea/js-primea-hypervisor/blob/317d79e49cb56dd81cb9c94072cd24ad6a825757/portManager.js#L164-L166 "Source code on GitHub")
96	96
97	97	gets a port given it's name
98	98
99	99	Parameters
		@@ -103,9 +103,9 @@
103	103	Returns [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)
104	104
105	105	## create
106	106
107		-[portManager.js:174-193](https://github.com/primea/js-primea-hypervisor/blob/b507f49239a73767abbee979b4e637a6ca469764/portManager.js#L174-L193 "Source code on GitHub")
	107	+[portManager.js:174-193](https://github.com/primea/js-primea-hypervisor/blob/317d79e49cb56dd81cb9c94072cd24ad6a825757/portManager.js#L174-L193 "Source code on GitHub")
108	108
109	109	creates a new container. Returning a port to it.
110	110
111	111	Parameters
		@@ -116,17 +116,17 @@
116	116	Returns [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)
117	117
118	118	## createChannel
119	119
120		-[portManager.js:199-213](https://github.com/primea/js-primea-hypervisor/blob/b507f49239a73767abbee979b4e637a6ca469764/portManager.js#L199-L213 "Source code on GitHub")
	120	+[portManager.js:199-213](https://github.com/primea/js-primea-hypervisor/blob/317d79e49cb56dd81cb9c94072cd24ad6a825757/portManager.js#L199-L213 "Source code on GitHub")
121	121
122	122	creates a channel returns the created ports in an Array
123	123
124	124	Returns [array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)
125	125
126	126	## getNextMessage
127	127
128		-[portManager.js:229-257](https://github.com/primea/js-primea-hypervisor/blob/b507f49239a73767abbee979b4e637a6ca469764/portManager.js#L229-L257 "Source code on GitHub")
	128	+[portManager.js:229-257](https://github.com/primea/js-primea-hypervisor/blob/317d79e49cb56dd81cb9c94072cd24ad6a825757/portManager.js#L229-L257 "Source code on GitHub")
129	129
130	130	Waits for the the next message if any
131	131
132	132	Returns [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)

kernel.jsView
		@@ -3,15 +3,15 @@
3	3	const DeleteMessage = require('./deleteMessage')
4	4
5	5	module.exports = class Kernel {
6	6	/**
7		- * the ExoInterface manages the varous message passing functions and provides
	7	+ * the Kernel manages the varous message passing functions and provides
8	8	* an interface for the containers to use
9	9	* @param {Object} opts
10		- * @param {Object} opts.id
11		- * @param {Object} opts.state
	10	+ * @param {Object} opts.id - the UUID of the Kernel
	11	+ * @param {Object} opts.state - the state of the container
12	12	* @param {Object} opts.hypervisor
13		- * @param {Object} opts.Container
	13	+ * @param {Object} opts.container - the container constuctor and argments
14	14	*/
15	15	constructor (opts) {
16	16	this.state = opts.state
17	17	this.hypervisor = opts.hypervisor
		@@ -70,10 +70,10 @@
70	70	}
71	71
72	72	/**
73	73	* run the kernels code with a given enviroment
74		- * The Kernel Stores all of its state in the Environment. The Interface is used
75		- * to by the VM to retrive infromation from the Environment.
	74	+ * @param {object} message - the message to run
	75	+ * @param {boolean} init - whether or not to run the intialization routine
76	76	* @returns {Promise}
77	77	*/
78	78	async run (message, init = false) {
79	79	let result

examples/index.jsView
		@@ -1,0 +1,82 @@
	1	+const IPFS = require('ipfs')
	2	+const Hypervisor = require('../')
	3	+
	4	+// the hypervisor store all of it's state using ipfs.dag api
	5	+// https://github.com/ipfs/interface-ipfs-core/tree/master/API/dag
	6	+const node = new IPFS({
	7	+ start: false
	8	+})
	9	+
	10	+// the Hypervisor starts an manages "containers" each container is
	11	+class ExampleContainer {
	12	+ // the constructor is given an instance of the kernel
	13	+ // https://github.com/primea/js-primea-hypervisor/blob/master/docs/kernel.md
	14	+ constructor (kernel) {
	15	+ this.kernel = kernel
	16	+ }
	17	+
	18	+ // this method runs once when the container is intailly created. It is given
	19	+ // a message with a single port, which is a channel to its parent with the
	20	+ // exception of the root container (the container that is intailial created)
	21	+ initailize (message) {
	22	+ const port = message.ports[0]
	23	+ // the root container doesn't get a port
	24	+ if (port) {
	25	+ this.kernel.ports.bind('parent', port)
	26	+ }
	27	+ }
	28	+
	29	+ // the function is called for each message that a container gets
	30	+ run (message) {
	31	+ console.log('message recived!', message.data)
	32	+ if (message.data === 'bindPort') {
	33	+ this.kernel.ports.bind('channel', message.ports[0])
	34	+ }
	35	+ }
	36	+}
	37	+
	38	+// wait untill the ipfs node is ready
	39	+node.on('ready', async() => {
	40	+ // create a new hypervisor instance
	41	+ const hypervisor = new Hypervisor(node.dag)
	42	+ hypervisor.registerContainer('example', ExampleContainer)
	43	+
	44	+ // create a root instance of the example container
	45	+ const root = await hypervisor.createInstance('example')
	46	+
	47	+ // create two instances of the example container. These containers wiil be
	48	+ // given channels to the parent container
	49	+ const portRef1 = root.ports.create('example')
	50	+ const portRef2 = root.ports.create('example')
	51	+
	52	+ // bind the ports of the newly created containers. Binding ports allows the
	53	+ // root container tot receieve messages from the containers. If no other
	54	+ // container bound these ports then the corrisponding containers would be
	55	+ // garbage collected
	56	+ root.ports.bind('one', portRef1)
	57	+ root.ports.bind('two', portRef2)
	58	+
	59	+ // create a new channel. Each channel has two corrisponding ports that
	60	+ // containers can communicate over
	61	+ const [chanRef1, chanRef2] = root.ports.createChannel()
	62	+ // send the newly created ports to each of the containers. Once both the
	63	+ // recieving containers bind the ports they will be able to communicate
	64	+ // directly with each other over them
	65	+ await root.send(portRef1, root.createMessage({
	66	+ data: 'bindPort',
	67	+ ports: [chanRef1]
	68	+ }))
	69	+
	70	+ await root.send(portRef2, root.createMessage({
	71	+ data: 'bindPort',
	72	+ ports: [chanRef2]
	73	+ }))
	74	+
	75	+ // create a new state root. The state root is not created untill the
	76	+ // hypervisor has finished all of it's work
	77	+ const stateRoot = await hypervisor.createStateRoot()
	78	+ console.log(stateRoot)
	79	+ console.log('--------full state dump---------')
	80	+ await hypervisor.graph.tree(stateRoot, Infinity)
	81	+ console.log(JSON.stringify(stateRoot, null, 2))
	82	+})

Built with git-ssb-web

wanderer🌟 / js-primea-hypervisor

Commit 74ccd6e33a63430ec22a6fcbfd0fd40f10c349c5

added example

Files changed