Wiki » History » Version 3

R. Haschke, 08/27/2014 10:40 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
8 2 J. Wienke
9 2 J. Wienke
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 1 J. Wienke
23 1 J. Wienke
24 3 R. Haschke
h2. Component Functions
25 3 R. Haschke
26 3 R. Haschke
h3. component
27 3 R. Haschke
28 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.
29 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.
30 3 R. Haschke
The component is considered as stopped if the component function terminates, i.e. the last process terminates.
31 3 R. Haschke
32 3 R. Haschke
h3. stop_component
33 3 R. Haschke
34 3 R. Haschke
Stopping of components often needs to be customized to adapt to the special requirements of more complex components, starting several processes.
35 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. 
36 3 R. Haschke
This function sends the given signal to all top-level processes spawned in the function @component@.
37 3 R. Haschke
38 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.
39 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.
40 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:
41 3 R. Haschke
42 3 R. Haschke
43 3 R. Haschke
	local PIDS=$(all_children --filter bash\|tee\|screen $(vdemo_pidFromScreen $1))
44 3 R. Haschke
	echo "killing processes $PIDS"
45 3 R. Haschke
	kill -SIGINT $PIDS > /dev/null 2>&1
46 3 R. Haschke
	for i in {1..50}; do
47 3 R. Haschke
		sleep 0.1
48 3 R. Haschke
		kill -0 $PIDS > /dev/null 2>&1 || break
49 3 R. Haschke
50 3 R. Haschke
51 3 R. Haschke
52 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.
53 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).
54 3 R. Haschke
55 3 R. Haschke
h3. on_check
56 3 R. Haschke
57 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.
58 3 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.
59 3 R. Haschke
If non-zero, the component is considered to be in an error state.
60 3 R. Haschke
61 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:
62 3 R. Haschke
63 3 R. Haschke
64 3 R. Haschke
65 3 R. Haschke
66 3 R. Haschke
|{background:green}.check|running + responding|
67 3 R. Haschke
|{background:orange}.check|responding, but not started from vdemo|
68 3 R. Haschke
|{background:pink}.check|running, but not responding|
69 3 R. Haschke
|{background:red}.check|not running|