git ssb

0+

wanderer🌟 / js-primea-hypervisor



Commit aff7fe3dbdadaa720feb5561633c1d5eb583f80d

update and rebuild docs

Norton Wang committed on 4/29/2018, 4:20:04 PM
Parent: 4ef01e25f0db10ce812670a695cf71a5ac9aba76

Files changed

actor.jschanged
docs/actor.mdchanged
docs/hypervisor.mdchanged
index.jschanged
actor.jsView
@@ -2,17 +2,18 @@
22 const nope = () => {}
33
44 module.exports = class Actor {
55 /**
6- * the Actor manages the varous message passing functions and provides
6 + * the Actor manages the various message passing functions and provides
77 * an interface for the containers to use
88 * @param {Object} opts
99 * @param {ID} opts.id - the UUID of the Actor
10- * @param {Object} opts.state - the state of the container
11- * @param {Object} opts.storage - the actor's persistant storage
10 + * @param {Object} opts.module - the module this actor was created from
11 + * @param {Object} opts.state - the state of the module
12 + * @param {Object} opts.storage - the actor's persistent storage
1213 * @param {Object} opts.hypervisor - the instance of the hypervisor
1314 * @param {Number} opts.nonce
14- * @param {Function} opts.container - the container constuctor and argments
15 + * @param {Function} opts.Container - the module constructor and arguments
1516 */
1617 constructor (opts) {
1718 Object.assign(this, opts)
1819
@@ -74,8 +75,9 @@
7475 /**
7576 * creates an actor from a module and code
7677 * @param {Module} mod - the module
7778 * @param {Buffer} code - the code
79 + * @return {ActorRef}
7880 */
7981 newActor (mod, code) {
8082 const modRef = this.createModule(mod, code)
8183 return this.createActor(modRef)
@@ -84,8 +86,9 @@
8486 /**
8587 * creates a modref from a module and code
8688 * @param {Module} mod - the module
8789 * @param {Buffer} code - the code
90 + * @return {ModuleRef}
8891 */
8992 createModule (mod, code) {
9093 const id = this._generateNextId()
9194 return this.hypervisor.createModule(mod, code, id)
@@ -93,8 +96,9 @@
9396
9497 /**
9598 * creates an actor from a modref
9699 * @param {ModuleRef} modRef - the modref
100 + * @return {ActorRef}
97101 */
98102 createActor (modRef) {
99103 const id = this._generateNextId()
100104 return this.hypervisor.createActor(modRef, id)
@@ -110,10 +114,9 @@
110114 return id
111115 }
112116
113117 /**
114- * sends a message to a given port
115- * @param {Object} portRef - the port
118 + * sends a message
116119 * @param {Message} message - the message
117120 */
118121 send (message) {
119122 message._fromTicks = this.ticks
docs/actor.mdView
@@ -6,86 +6,95 @@
66 - [shutdown][2]
77 - [startup][3]
88 - [runMessage][4]
99 - [incrementTicks][5]
10-- [createActor][6]
11-- [send][7]
10 +- [newActor][6]
11 +- [createModule][7]
12 +- [createActor][8]
13 +- [send][9]
1214
1315 ## constructor
1416
15-[actor.js:17-26][8]
16-
17-the Actor manages the varous message passing functions and provides
17 +the Actor manages the various message passing functions and provides
1818 an interface for the containers to use
1919
2020 **Parameters**
2121
22-- `opts` **[Object][9]**
22 +- `opts` **[Object][10]**
2323 - `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
24 + - `opts.module` **[Object][10]** the module this actor was created from
25 + - `opts.state` **[Object][10]** the state of the module
26 + - `opts.storage` **[Object][10]** the actor's persistent storage
27 + - `opts.hypervisor` **[Object][10]** the instance of the hypervisor
28 + - `opts.nonce` **[Number][11]**
29 + - `opts.Container` **[Function][12]** the module constructor and arguments
3030
3131 ## shutdown
3232
33-[actor.js:31-35][12]
34-
3533 Runs the shutdown routine for the actor
3634
3735 ## startup
3836
39-[actor.js:40-42][13]
40-
4137 Runs the startup routine for the actor
4238
4339 ## runMessage
4440
45-[actor.js:50-61][14]
46-
4741 run the Actor with a given message
4842
4943 **Parameters**
5044
51-- `message` **[object][9]** the message to run
52-- `method` **[String][15]** which method to run
45 +- `message` **[object][10]** the message to run
46 +- `method` **[String][13]** which method to run
5347
54-Returns **[Promise][16]**
48 +Returns **[Promise][14]**
5549
5650 ## incrementTicks
5751
58-[actor.js:67-73][17]
59-
6052 updates the number of ticks that the actor has run
6153
6254 **Parameters**
6355
64-- `count` **[Number][10]** the number of ticks to add
56 +- `count` **[Number][11]** the number of ticks to add
6557
66-## createActor
58 +## newActor
6759
68-[actor.js:80-83][18]
60 +creates an actor from a module and code
6961
70-creates an actor
62 +**Parameters**
7163
64 +- `mod` **[Module][15]** the module
65 +- `code` **[Buffer][16]** the code
66 +
67 +Returns **ActorRef**
68 +
69 +## createModule
70 +
71 +creates a modref from a module and code
72 +
7273 **Parameters**
7374
74-- `type` **Integer** the type id for the container
75-- `code`
76-- `message` **[Object][9]** an intial [message][19] to send newly created actor
75 +- `mod` **[Module][15]** the module
76 +- `code` **[Buffer][16]** the code
7777
78-## send
78 +Returns **ModuleRef**
7979
80-[actor.js:100-105][20]
80 +## createActor
8181
82-sends a message to a given port
82 +creates an actor from a modref
8383
8484 **Parameters**
8585
86 +- `modRef` **ModuleRef** the modref
87 +
88 +Returns **ActorRef**
89 +
90 +## send
91 +
92 +sends a message
93 +
94 +**Parameters**
95 +
8696 - `message` **Message** the message
87-- `portRef` **[Object][9]** the port
8897
8998 [1]: #constructor
9099
91100 [2]: #shutdown
@@ -95,33 +104,25 @@
95104 [4]: #runmessage
96105
97106 [5]: #incrementticks
98107
99-[6]: #createactor
108 +[6]: #newactor
100109
101-[7]: #send
110 +[7]: #createmodule
102111
103-[8]: https://github.com/dfinity/js-primea/blob/1f8affb407f9413e9af400e3cc7408ece8274347/actor.js#L17-L26 "Source code on GitHub"
112 +[8]: #createactor
104113
105-[9]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
114 +[9]: #send
106115
107-[10]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number
116 +[10]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
108117
109-[11]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function
118 +[11]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number
110119
111-[12]: https://github.com/dfinity/js-primea/blob/1f8affb407f9413e9af400e3cc7408ece8274347/actor.js#L31-L35 "Source code on GitHub"
120 +[12]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function
112121
113-[13]: https://github.com/dfinity/js-primea/blob/1f8affb407f9413e9af400e3cc7408ece8274347/actor.js#L40-L42 "Source code on GitHub"
122 +[13]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
114123
115-[14]: https://github.com/dfinity/js-primea/blob/1f8affb407f9413e9af400e3cc7408ece8274347/actor.js#L50-L61 "Source code on GitHub"
124 +[14]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise
116125
117-[15]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
126 +[15]: https://nodejs.org/api/modules.html
118127
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"
128 +[16]: https://nodejs.org/api/buffer.html
docs/hypervisor.mdView
@@ -4,157 +4,150 @@
44
55 - [constructor][1]
66 - [send][2]
77 - [loadActor][3]
8-- [createActor][4]
9-- [createStateRoot][5]
10-- [setStateRoot][6]
11-- [registerContainer][7]
12-- [registerDriver][8]
8 +- [newActor][4]
9 +- [createModule][5]
10 +- [createActor][6]
11 +- [createStateRoot][7]
12 +- [setStateRoot][8]
13 +- [registerModule][9]
14 +- [registerDriver][10]
1315
1416 ## constructor
1517
16-[index.js:18-27][9]
18 +The Hypervisor manages module instances by instantiating them and
19 +destroying them when possible. It also facilitates locating Containers
1720
18-The Hypervisor manages the container instances by instantiating them and
19-destorying them when possible. It also facilitates localating Containers
20-
2121 **Parameters**
2222
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`)
23 +- `opts` **[Object][11]**
24 + - `opts.tree` **[Object][11]** a [radix tree][12] to store the state
25 + - `opts.modules` **[Array][13]** an array of modules to register
26 + - `opts.drivers` **[Array][13]** an array of drivers to install
27 + - `opts.meter` **[boolean][14]** whether to meter gas or not (optional, default `true`)
2828
2929 ## send
3030
31-[index.js:34-39][14]
32-
3331 sends a message(s). If an array of message is given the all the messages will be sent at once
3432
3533 **Parameters**
3634
3735 - `messages`
38-- `message` **[Object][10]** the [message][15] to send
36 +- `message` **[Object][11]** the [message][15] to send
3937
40-Returns **[Promise][16]** a promise that resolves once the receiving container is loaded
38 +Returns **[Promise][16]** a promise that resolves once the receiving module is loaded
4139
4240 ## loadActor
4341
44-[index.js:46-70][17]
45-
4642 loads an actor from the tree given its id
4743
4844 **Parameters**
4945
5046 - `id` **ID**
5147
5248 Returns **[Promise][16]<Actor>**
5349
54-## createActor
50 +## newActor
5551
56-[index.js:78-102][18]
52 +creates an actor from a module and code
5753
58-creates an instance of an Actor
54 +**Parameters**
5955
56 +- `mod` **[Module][17]** the module
57 +- `code` **[Buffer][18]** the code
58 +
59 +Returns **ActorRef**
60 +
61 +## createModule
62 +
63 +creates a modref from a module and code
64 +
6065 **Parameters**
6166
62-- `type` **Integer** the type id for the container
63-- `code`
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
67 +- `mod` **[Module][17]** the module
68 +- `code` **[Buffer][18]** the code
69 +- `id` **id** the id for the module (optional, default `{nonce:this.nonce++,parent:null}`)
6670
67-## createStateRoot
71 +Returns **ModuleRef**
6872
69-[index.js:116-124][19]
73 +## createActor
7074
71-creates a state root starting from a given container and a given number of
72-ticks
75 +creates an instance of an Actor
7376
7477 **Parameters**
7578
76-- `ticks` **[Number][20]** the number of ticks at which to create the state root
79 +- `modRef`
80 +- `id` **[Object][11]** the id for the actor (optional, default `{nonce:this.nonce++,parent:null}`)
81 +- `type` **ModuleRef** the modref
7782
83 +Returns **ActorRef**
84 +
85 +## createStateRoot
86 +
87 +creates a state root when scheduler is idle
88 +
7889 Returns **[Promise][16]**
7990
8091 ## setStateRoot
8192
82-[index.js:131-135][21]
83-
8493 set the state root. The promise must resolve before creating or sending any more messages to the hypervisor
8594
8695 **Parameters**
8796
88-- `stateRoot` **[Buffer][22]**
97 +- `stateRoot` **[Buffer][18]**
8998
9099 Returns **[Promise][16]**
91100
92-## registerContainer
101 +## registerModule
93102
94-[index.js:141-143][23]
103 +registers a module with the hypervisor
95104
96-regesters a container with the hypervisor
97-
98105 **Parameters**
99106
100-- `Constructor` **[Function][24]** the container's constuctor
107 +- `Constructor` **[Function][19]** the module's constructor
101108
102109 ## registerDriver
103110
104-[index.js:149-151][25]
105-
106111 register a driver with the hypervisor
107112
108113 **Parameters**
109114
110-- `driver` **driver**
115 +- `driver` **Driver**
111116
112117 [1]: #constructor
113118
114119 [2]: #send
115120
116121 [3]: #loadactor
117122
118-[4]: #createactor
123 +[4]: #newactor
119124
120-[5]: #createstateroot
125 +[5]: #createmodule
121126
122-[6]: #setstateroot
127 +[6]: #createactor
123128
124-[7]: #registercontainer
129 +[7]: #createstateroot
125130
126-[8]: #registerdriver
131 +[8]: #setstateroot
127132
128-[9]: https://github.com/dfinity/js-primea/blob/1f8affb407f9413e9af400e3cc7408ece8274347/index.js#L18-L27 "Source code on GitHub"
133 +[9]: #registermodule
129134
130-[10]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
135 +[10]: #registerdriver
131136
132-[11]: https://github.com/dfinity/js-dfinity-radix-tree
137 +[11]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
133138
134-[12]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array
139 +[12]: https://github.com/dfinity/js-dfinity-radix-tree
135140
136-[13]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean
141 +[13]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array
137142
138-[14]: https://github.com/dfinity/js-primea/blob/1f8affb407f9413e9af400e3cc7408ece8274347/index.js#L34-L39 "Source code on GitHub"
143 +[14]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean
139144
140145 [15]: https://github.com/primea/js-primea-message
141146
142147 [16]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise
143148
144-[17]: https://github.com/dfinity/js-primea/blob/1f8affb407f9413e9af400e3cc7408ece8274347/index.js#L46-L70 "Source code on GitHub"
149 +[17]: https://nodejs.org/api/modules.html
145150
146-[18]: https://github.com/dfinity/js-primea/blob/1f8affb407f9413e9af400e3cc7408ece8274347/index.js#L78-L102 "Source code on GitHub"
151 +[18]: https://nodejs.org/api/buffer.html
147152
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"
153 +[19]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function
index.jsView
@@ -4,13 +4,13 @@
44 const {decoder, generateId, ModuleRef, ActorRef} = require('primea-objects')
55
66 module.exports = class Hypervisor {
77 /**
8- * The Hypervisor manages the container instances by instantiating them and
9- * destorying them when possible. It also facilitates localating Containers
8 + * The Hypervisor manages module instances by instantiating them and
9 + * destroying them when possible. It also facilitates locating Containers
1010 * @param {Object} opts
1111 * @param {Object} opts.tree - a [radix tree](https://github.com/dfinity/js-dfinity-radix-tree) to store the state
12- * @param {Array} opts.container - an array of containers to regester
12 + * @param {Array} opts.modules - an array of modules to register
1313 * @param {Array} opts.drivers - an array of drivers to install
1414 * @param {boolean} [opts.meter=true] - whether to meter gas or not
1515 */
1616 constructor (opts) {
@@ -26,9 +26,9 @@
2626
2727 /**
2828 * sends a message(s). If an array of message is given the all the messages will be sent at once
2929 * @param {Object} message - the [message](https://github.com/primea/js-primea-message) to send
30- * @returns {Promise} a promise that resolves once the receiving container is loaded
30 + * @returns {Promise} a promise that resolves once the receiving module is loaded
3131 */
3232 send (messages) {
3333 if (!Array.isArray(messages)) {
3434 messages = [messages]
@@ -46,8 +46,9 @@
4646 const [module, storage] = await Promise.all([
4747 this.tree.graph.tree(state.node, '1'),
4848 this.tree.graph.get(state.node, '2')
4949 ])
50 + await this.tree.graph.get(module[1][1], '')
5051 const [type, nonce] = state.value
5152 const Container = this._modules[type]
5253
5354 // create a new actor instance
@@ -65,24 +66,38 @@
6566 await actor.startup()
6667 return actor
6768 }
6869
70 + /**
71 + * creates an actor from a module and code
72 + * @param {Module} mod - the module
73 + * @param {Buffer} code - the code
74 + * @return {ActorRef}
75 + */
6976 newActor (mod, code) {
7077 const modRef = this.createModule(mod, code)
7178 return this.createActor(modRef)
7279 }
7380
81 + /**
82 + * creates a modref from a module and code
83 + * @param {Module} mod - the module
84 + * @param {Buffer} code - the code
85 + * @param {id} id - the id for the module
86 + * @return {ModuleRef}
87 + */
7488 createModule (mod, code, id = {nonce: this.nonce++, parent: null}) {
7589 const moduleID = generateId(id)
7690 const Module = this._modules[mod.typeId]
77- const {exports, state} = Module.onCreation(mod.code)
91 + const {exports, state} = Module.onCreation(code)
7892 return new ModuleRef(moduleID, mod.typeId, exports, state, code)
7993 }
8094
8195 /**
8296 * creates an instance of an Actor
83- * @param {Integer} type - the type id for the container
97 + * @param {ModuleRef} type - the modref
8498 * @param {Object} id - the id for the actor
99 + * @return {ActorRef}
85100 */
86101 createActor (modRef, id = {nonce: this.nonce++, parent: null}) {
87102 const actorId = generateId(id)
88103 const metaData = [modRef.type, 0]
@@ -102,20 +117,18 @@
102117 return new ActorRef(actorId, modRef)
103118 }
104119
105120 /**
106- * creates a state root starting from a given container and a given number of
107- * ticks
108- * @param {Number} ticks the number of ticks at which to create the state root
121 + * creates a state root when scheduler is idle
109122 * @returns {Promise}
110123 */
111124 async createStateRoot () {
112125 if (this.scheduler._running) {
113126 await new Promise((resolve, reject) => {
114127 this.scheduler.once('idle', resolve)
115128 })
116129 }
117- // console.log(JSON.stringify(this.tree.root, null, 2))
130 +
118131 await this.tree.set(Buffer.from([0]), this.nonce)
119132 return this.tree.flush()
120133 }
121134
@@ -130,18 +143,18 @@
130143 this.nonce = node.value
131144 }
132145
133146 /**
134- * regesters a container with the hypervisor
135- * @param {Function} Constructor - the container's constuctor
147 + * registers a module with the hypervisor
148 + * @param {Function} Constructor - the module's constructor
136149 */
137150 registerModule (Constructor) {
138151 this._modules[Constructor.typeId] = Constructor
139152 }
140153
141154 /**
142155 * register a driver with the hypervisor
143- * @param {driver} driver
156 + * @param {Driver} driver
144157 */
145158 registerDriver (driver) {
146159 driver.startup(this)
147160 this.scheduler.drivers.set(driver.id.toString(), driver)

Built with git-ssb-web