Wiki » History » Version 9

J. Wienke, 10/27/2014 11:16 AM

1 1 J. Wienke
h1. Wiki
2 1 J. Wienke
3 3 R. Haschke
[[OldAiDocumentation|Documentation from old AI Trac]]
4 3 R. Haschke
5 2 J. Wienke
h2. Component List Syntax
6 2 J. Wienke
7 2 J. Wienke
<pre>
8 2 J. Wienke
COMPONENT LIST	
9 2 J. Wienke
   Options:
10 2 J. Wienke
      -w <n> wait n seconds for process to start completely
11 1 J. Wienke
      -c     run check every second during wait and break if component is running
12 3 R. Haschke
      -W <n> set delay when an asynchronous check is performed in case -w is not specified
13 1 J. Wienke
      -l     activate initial logging for the component
14 2 J. Wienke
      -x     use own X server for the component
15 3 R. Haschke
      -n     do not include in level/group/auto start
16 2 J. Wienke
      -g <s> allow to define a group (string: name of group)
17 2 J. Wienke
      -L <n> component level, affects starting order (numeric: level)
18 2 J. Wienke
      -d <n> detach time, automatically detaches screen after n seconds, or
19 2 J. Wienke
             leaves it open all the time (-1), default is 10 seconds
20 2 J. Wienke
      -t     title of the component / provide unique names for multiple instances on the same host
21 1 J. Wienke
      -v     export variable varname=var to component script
22 9 J. Wienke
      -Q     Stop the whole vdemo system in a clean fashion in case the respective components
23 9 J. Wienke
             stops on its own (or is killed externally) but not when the stop button is pressed
24 1 J. Wienke
</pre>
25 1 J. Wienke
26 3 R. Haschke
h2. Component Functions
27 3 R. Haschke
28 3 R. Haschke
h3. component
29 3 R. Haschke
30 3 R. Haschke
Called to start the component. All variables to be used in this function, either need to be exported to the environment beforehand or defined locally within the function.
31 3 R. Haschke
Several processes can be launched in the @component@ function (and send to background). However, the main process should be launched last and *must not* be send to background.
32 3 R. Haschke
The component is considered as stopped if the component function terminates, i.e. the last process terminates.
33 3 R. Haschke
34 3 R. Haschke
h3. stop_component
35 3 R. Haschke
36 3 R. Haschke
Stopping of components often needs to be customized to adapt to the special requirements of more complex components, starting several processes.
37 3 R. Haschke
The default behaviour is to call @vdemo_stop_signal_children $1 SIGINT 2@, where $1 is the title of the component provided as an argument by vdemo, @SIGINT@ is the signal to use for stopping, and 2 is a 2sec timeout to wait for the processes to be stopped. 
38 3 R. Haschke
This function sends the given signal to all top-level processes spawned in the function @component@.
39 3 R. Haschke
40 3 R. Haschke
However, some processes ignore SIGINT or take longer to shutdown. In this case you should customize the stopping behaviour, specifying an own @stop_component@ function.
41 3 R. Haschke
An important example are shell scripts which are launched from the @component@ function: bash doesn't react to @SIGINT@ at all. Sending a @SIGTERM@ quits bash, but leaves launched child processes open.
42 3 R. Haschke
A prominent example is MaryServer, which is launching java from a bash script within the @component@ function. This component requires the following stop function:
43 3 R. Haschke
44 3 R. Haschke
<pre>
45 4 R. Haschke
function stop_component {
46 3 R. Haschke
	local PIDS=$(all_children --filter bash\|tee\|screen $(vdemo_pidFromScreen $1))
47 3 R. Haschke
	echo "killing processes $PIDS"
48 3 R. Haschke
	kill -SIGINT $PIDS > /dev/null 2>&1
49 3 R. Haschke
	for i in {1..50}; do
50 3 R. Haschke
		sleep 0.1
51 3 R. Haschke
		kill -0 $PIDS > /dev/null 2>&1 || break
52 3 R. Haschke
	done
53 4 R. Haschke
}
54 3 R. Haschke
</pre>
55 3 R. Haschke
56 3 R. Haschke
The function @all_children@ provided by @vdemo@ lists all PIDs of the component's screen process and its children, eventually filtering out the given command names.
57 3 R. Haschke
Subsequently, these processes can be killed. The loop waits for actual termination of those processes (with a timeout of 5s = 50*0.1s).
58 3 R. Haschke
59 3 R. Haschke
h3. on_check
60 3 R. Haschke
61 3 R. Haschke
Typically a component is considered to be running, when its corresponding screen process is alive. However, some components might be broken/not responding although there are still running.
62 6 R. Haschke
To this end, the function @on_check@ can be provided. If present, the function is called additionally to the screen-process-alive test and its _return value_ is used to judge the state of the component.
63 5 R. Haschke
If non-zero, the component is considered to be in an error state. A typical example is to check for responsiveness of a specific port:
64 5 R. Haschke
65 5 R. Haschke
<pre>
66 5 R. Haschke
function on_check {
67 5 R. Haschke
	nc -w 1 -z 0.0.0.0 "$SPREAD_PORT"
68 5 R. Haschke
}
69 5 R. Haschke
</pre>
70 5 R. Haschke
71 3 R. Haschke
72 3 R. Haschke
Vice-versa, components might be running independently from vdemo, and thus often interfere with a demo. In this case on_check would indicate a running component, although no screen process is present. This is indicated in vdemo with orange component color. The following indicator colors are used:
73 3 R. Haschke
74 3 R. Haschke
table{border:0px}.
75 3 R. Haschke
|{background:lightgray}.check|unknown|
76 3 R. Haschke
|{background:yellow}.check|starting|
77 3 R. Haschke
|{background:green}.check|running + responding|
78 3 R. Haschke
|{background:orange}.check|responding, but not started from vdemo|
79 3 R. Haschke
|{background:pink}.check|running, but not responding|
80 3 R. Haschke
|{background:red}.check|not running|
81 7 R. Haschke
82 7 R. Haschke
h2. Spread configuration
83 7 R. Haschke
84 7 R. Haschke
To facilitate creation of spread configuration files, a spread configuration is automatically generated when no SPREAD_CONFIG environment variable is defined in the master script.
85 7 R. Haschke
To this end, all machines where a spread daemon should be started, are grouped into segments using the _first_ three IP octets. For each segment an own spread multicast group is created
86 7 R. Haschke
using the multicast IP address 225.xxx.yyy.zzz where the three octets xxx.yyy.zzz are the _last_ three IP octets of the first machine within a segment.
87 8 R. Haschke
This way, we hope to ensure, that every setup configuration obtains its own multicast groups.