Wiki » History » Version 3

« Previous - Version 3/19 (diff) - Next » - Current version
R. Haschke, 08/27/2014 10:40 AM


Documentation from old AI Trac

Component List Syntax

      -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

Component Functions


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.


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:

    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

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).


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:

check unknown
check starting
check running + responding
check responding, but not started from vdemo
check running, but not responding
check not running