vdemo

h1. Wiki

[[OldAiDocumentation|Documentation from old AI Trac]]

h2. Component List Syntax

<pre>

COMPONENT LIST	

   Options:

      -w <n> wait n seconds for process to start completely

      -c     run check every second during wait and break if component is running

      -W <n> set delay when an asynchronous check is performed in case -w is not specified

      -l     activate initial logging for the component

      -x     use own X server for the component

      -n     do not include in level/group/auto start

      -g <s> allow to define a group (string: name of group)

      -L <n> component level, affects starting order (numeric: level)

      -d <n> detach time, automatically detaches screen after n seconds, or

             leaves it open all the time (-1), default is 10 seconds

      -t     title of the component / provide unique names for multiple instances on the same host

      -v     export variable varname=var to component script

</pre>

h2. Component Functions

h3. component

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.

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.

The component is considered as stopped if the component function terminates, i.e. the last process terminates.

h3. stop_component

Stopping of components often needs to be customized to adapt to the special requirements of more complex components, starting several processes.

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. 

This function sends the given signal to all top-level processes spawned in the function @component@.

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.

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.

A prominent example is MaryServer, which is launching java from a bash script within the @component@ function. This component requires the following stop function:

<pre>

	local PIDS=$(all_children --filter bash\|tee\|screen $(vdemo_pidFromScreen $1))

	echo "killing processes $PIDS"

	kill -SIGINT $PIDS > /dev/null 2>&1

	for i in {1..50}; do

		sleep 0.1

		kill -0 $PIDS > /dev/null 2>&1 || break

	done

</pre>

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.

Subsequently, these processes can be killed. The loop waits for actual termination of those processes (with a timeout of 5s = 50*0.1s).

h3. on_check

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.

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.

If non-zero, the component is considered to be in an error state.

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:

table{border:0px}.

|{background:lightgray}.check|unknown|

|{background:yellow}.check|starting|

|{background:green}.check|running + responding|

|{background:orange}.check|responding, but not started from vdemo|

|{background:pink}.check|running, but not responding|

|{background:red}.check|not running|