Project

General

Profile

Channel environment and server in Scol » History » Version 3

iri, 09/25/2012 01:01 AM

1 1 iri
h1. Channel environment and server in Scol
2
3
{{toc}}
4
5
A channel is a pair : an environment and a network connection.
6
The network connection is mostly a TCP/IP socket connection, UDP sometimes. However, a channel can contain no network conenction : in this case, the channel is named unplugged. But a channel always has an environment. The network connection is managed by Scol itself, not by the developer.
7
8
In each VM, there is one channel (or more), the first channel is always unplugged, it is automatically created and, initially, gets the minimal environment. If this first channel is destroyed, the VM is destroyed.
9
A second channel is created between this new VM and the primary VM (or mother, or ScolEngine or Supervisor ... it is the same thing), except if it is the primary VM ! The new VM is destroyed if this channel is destroyed.
10
If the channel of the mother is destroyed, all VMs are destroyed.
11
(cf socketLife)
12
13
An environment is a list of functions (and thus variables and other objects). It is never empty.
14
Initially, all environment is the minimal environment : only all loaded Scol APIs.
15
The loaded APIs are defined in the usm.ini file of each client (machine).
16
17
Each added package is loaded in the current environment (one who is in the channel used for loading). Thus, a package can refer to the functions and variables previously loaded. The minimal environment is at the end of the list. The last loaded package is at the head.
18
19
Example :
20
we have a launcher :
21
<pre>
22
_load "dir/package_3.pkg"
23
_load "dir/package_2.pkg"
24
_load "dir/package_1.pkg"
25
main
26
</pre>
27
28
In the list (the environment), we get :
29
30
@package_3 :: package_2 :: package_1 :: minimal environment :: nil@
31
32
The application can access to a function declared in package_1 from the package_1, 2 and 3.
33
The same application can access to a function declared in package_3 from the package_3 only.
34
35
A VM can manage several environment simultaneously. That is why this is important to know in which environment an object is created or used. The Scol function _channel returns the first created channel when a VM starts. Then, it is in this channel that you will mostly code.
36
37
Two environments in two differents channel can have a common part : they share several functions and variables. You can change the environment in any channel, get it, remove it, ... Two channels can have the same environment.
38
This is important to discern the diffrence between channel and environment.
39
40
So, in "Openspace3d":http://www.openspace3d.com (a free software written in Scol), each plugIT has its channel and its environment. All these environments are identical (functions and variables of Openspace3d + minimal environment) except the last loaded packages : the specific code of each plugIT.
41
42
Basically, in a client-server application, the client VM and the server VM have their channel. The client has also a channel to the server. The server has N more channel if N clients are connected.
43
44
That is important to order correctly the loading of packages.
45
46
You could read a log file : first, the differents APIs are loaded, as defined in usm.ini (and the same order). Next, each line of the launcher is loaded.
47
48
The channel Scol type is *Chn*.
49
The environment Scol type is *Env*.
50
The server Scol type is *Srv*.
51
52
53
h2. How to get an environment ?
54
55
By the Scol function *_envchannel*. It returns the environment (Env) :
56
57
@_envchannel <channel>@
58
59
<channel> : the channel whose you want to have the environment
60
61
62
h2. How to set an environment ?
63
64
After its creation, it is possible to change the environment from any channel.
65
66
@_setenv <channel> <new_environment>@
67
68
If <new_environment> is nil, this will be the minimal environment.
69
70
71
h2. How to remove the last environment ?
72
73
An environment is a list. To remove the last one (you find it in the first element of the list) :
74
75
@_removepkg <environment>@
76
This function returns the "sub-environment" (the same list less the first element).
77
Next, change the environment in the channel :
78
@_setenv <channel> <sub_environment>@
79
80
h3.Example :
81
82
this function removes the last package in the current channel
83
84
<pre>
85
fun removeTheLastPackageInTheCurrentChannel ()=
86
	let _envchannel _channel -> currentEnv in
87
	_setenv _channel _removepkg currentEnv;
88
	0;;	
89
</pre>
90
91
92
h2. How to list an environment ?
93
94
<pre>
95
fun getPackageNames (env)=
96
 	if env == nil then
97
		 nil
98
 	else 
99
 	(
100
 		_fooS _envfirstname env;	
101
 		getPackageNames _removepkg env
102
 	);;
103
 		
104
fun main ()=
105
	_showconsole;
106
	getPackageNames _envchannel _channel;
107
	0;;
108
</pre>
109
110
111
h2. How to create a channel ?
112
113
By default, a channel is always created when a new VM is initialized.
114
If you want more, you have *_openchannel* or *_setUDP*.
115
116
h3. _openchannel
117
118
*_openchannel* creates a new channel with a TCP/IP socket. It takes three arguments :
119
* an IP address:port, like "123.123.210.12:1234". If nil then the channel will be *unplugged* (without network connection)
120
* a script to execute once the creation done. The script is like a *.scol.
121
* an inherited environment. If nil then it will be the minimal environment.
122
123
This function is asynchronous. It returns immediately even if the connection is not done. When the connection is active, Scol searches in the application code a function named *_connected*. If found, _connected will be executed, otherwise it will be ignored. See below.
124
125
h3. _setUDP
126
127
*_setUDP* creates a new channel with an UDP conenction.
128
* an inherited environment
129
* a port number
130
* a script like a *.scol.
131
132
These two functions return the +new+ channel.
133
134
h2. How to get a channel ?
135
136
The current channel is returned by the Scol function *_channel*.
137
The channel linking the VM to the primary VM is returned by the Scol function *_masterchannel*.
138
139
h2. How to close a channel ?
140
141
You have two near functions : *_closechannel* and *_killchannel*. In the first, all objects are destroyed but the current function continues until its end.
142
143
When a channel is destroyed, the network connection is closed also. Scol searches in the application code if a function named *_closed* exists. If yes, it will be executed and next the program continue, if no, the program continue normally.
144
145
h2. How to create and close a Scol server ?
146
147
To communicate, the VM should have a server : a server is able to receive a connection and calculate or evaluate the request.
148
149
When a channel is created to a remote VM (or another local VM), the network conenction must be ok otherwise the new channel is immediately and automatically destroyed.
150
151
This is very simple to create a Scol server :
152
153
@_setserver <environment> <port_number> <script>;@
154
155
* The <environment> is the server environment : it can be the same than the application or another one. It will be inherited by each channel created from this server.
156
* The <port_number> must be opened and free. If this function returns nil, the port is probably already busy.
157
* The <script> is a (or more) packages loaded for each connection and the script is run in the new channel.
158
159
h3. To close a server :
160
161
@_closeserver <server>@
162
163
164
h2. How to send a data in a channel ?
165
166 2 iri
h3. On a TCP/IP channel
167
168 1 iri
First, to send a message in a channel, the network connection must be opened. If the channel is unplugged, all messages will be ignored.
169
To receive datas, the receiver must be also a server.
170
171
Next, you should build a communication object (Scol type : *Comm*).
172
A communication takes the form "command argument". command is the function that the receiver should execute, argument is the data to send.
173
On the receiver, the function *must* be *__command* (with two underscores) otherwise the message will be lost ! Next, once __command found, the types of arguments are checked. If all is ok, the function is ran. The result is not sent to the primary sender. For that, you must build a new communication from the receiver to the sender this time ...
174
175
To build a communication, you must declare it before its use. Two ways : *defcom* and *defcomvar*.
176
177
Like for a variable, to declare a communication you make :
178
179
<pre>
180
defcom <communication_name> = <command> <data_types>;;
181
defcomvar <communication_name> = <data_types>;; // here, you can change the <command>, see below
182
</pre>
183
184
Next, to send a communication, you use *_on* :
185
186
@_on <channel> <communication_name>;@
187
188
<channel> must be the channel to the receiver. This function returns 0 if success (no error occurred during the send).
189
190
Of course, if the receiver doesn't exist (destroyed, not yet created, etc), nothing will happen.
191
192 2 iri
h4. Example : 
193 1 iri
194
you want to send a message from Bob to Alice.
195
196 2 iri
h5. For Bob :
197 1 iri
198
<pre>
199
defcom commToAlice = funHello I S S;; // sent datas are an integer and two strings
200
typeof chnToAlice = Chn;;
201
202
fun main ()=
203
	_showconsole;
204
	
205
	let _envchannel _channel -> myEnv in
206 3 iri
    // create a channel to Alice with the same environment than Bob
207
	set chnToAlice = _openchannel "123.1.2.3:1234" nil myEnv; 
208 1 iri
	// do something
209
	let _on chnToAlice commToAlice [10 "This is Bob !" "I come in 5 minutes"] -> result in
210
	_fooS if result == 0 then
211
				"send OK"
212
			else
213
				"send KO";
214
	0;;
215
</pre>
216
	
217
	
218 2 iri
h5. For Alice :
219 1 iri
220
<pre>
221
typeof server = Srv;;
222
223
fun createServer ()=
224
	set server = _setserver _envchannel _channel 3500 nil;
225
	_fooS if server == nil then
226
			"Unable to create a server, the port is probably busy"
227
		else
228
			"Server created";
229
	0;;
230
231
fun main ()=
232
	_showconsole;
233
	createServer;
234
	0;;
235
236
fun __funHello (integer, string_1, string_2)=
237
	_fooId integer;
238
	_fooS string_1;
239
	_fooS string_2;
240
	0;;	
241
</pre>
242
243 3 iri
h3. On an UDP channel :
244 1 iri
245
A communication object is also needed. There is no difference with the TCP/IP connection (see above).
246
247
@_sendUDP <commande> <communication_name>@
248
or
249
@_sendUDPchn <channel_to_send> <command> <communication_name>@
250
251
To know the IP of a connection, use *_channelIP*.
252
253
254
255
h2. _connected and _closed
256
257
*_connected* is automatically and immediately called when a network connection occurs.
258
259
By example, a Scol server has been initialized with a valid script (see above, How to create and close a Scol server ?), the server environment can contain this function. In this case, it will be called at each new connection on the server. The return value is ignored and its type can be anything. If _coonected doesn't exist in the current environment, it is ignored.
260
Don't call yourself this function.
261
262
*_closed* is automatically called when a network connection closes.
263
264
This is the same thing than _connected.
265
266
267
h2. How to control message queues ?
268
269
After executing the _on function, the message is put in a queue to the channel. Few Scol functions get informations about queues.
270
271
h2. Example :
272
273
Let us consider two virtual machines "Bob" and "Alice" who can communicate (send and receive messages).
274
We create a server on each machine to receive message and we create a channel from Bob to Alice.
275
In our example, we should launch Alice, next Bob because we send the message to Alice immediately (our code is simple). Thus, Alice must exist to receive the message ...
276
277
This full example can be browsed from the "repository":http://redmine.scolring.org/projects/tutorials/repository/show/channel_environment_server.
278
279
	
280
	
281
h2. Others
282
283
There are several functions about environment, channel and communication in the standard Scol release and in the syspack Scol library. See the "official documentation":http://www.scolring.org/files/doc_html/.
284
285
286
License : "CC-BY-SA-2.0":https://creativecommons.org/licenses/by-sa/2.0/
287
Tutorial by iri
288
Updated by /