Description

The ADTF Launcher handles everything about launching an ADTF Session

launching an ADTF Session
provding remote access to running ADTF System

as comfortable command line tooling.

Getting started

For any purpose, please execute the adtf_launcher with the option --help, which will give you an overview and example usage of available options and commands.

ADTF Launcher
 
adtf_launcher
 
Usage:
        adtf_launcher --help
        adtf_launcher --version
        adtf_launcher --session <adtfsessionfile> [--active-streaming-graph <graphname>]
                      [--active-filter-graph <graphname>] [--environment <adtfenvironmentfile>]
                      [--adtf-core-plugin <adtfcorepluginfile>] [--control-url <url>]
                      [[--create|--init|--run] [--continue-execution-in-case-of-error]] [--quit]
                      [--quit-timeout <seconds>] [--profiler] [--profiler-port <port>]
                      [--profiler-dump-file <filename>] [--log-file <filename>]
                      [--log-processing-interval <microseconds>] [--log-level-stdout <level>]
                      [--log-level-stderr <level>] [--console|--detach] [--no-dump]
                      [--no-plugin-discovery] [-- [<argument>]...]
 
        adtf_launcher --system <adtfsystemfile> [--system-properties <adtfpropertiesfile>] [--graph
                      <adtfgraphfile>] [--graph-properties <adtfpropertiesfile>]
                      [--active-streaming-graph <graphname>] [--active-filter-graph <graphname>]
                      [--environment <adtfenvironmentfile>] [--adtf-core-plugin
                      <adtfcorepluginfile>] [--control-url <url>] [[--create|--init|--run]
                      [--continue-execution-in-case-of-error]] [--quit] [--quit-timeout <seconds>]
                      [--profiler] [--profiler-port <port>] [--profiler-dump-file <filename>]
                      [--log-file <filename>] [--log-processing-interval <microseconds>]
                      [--log-level-stdout <level>] [--log-level-stderr <level>] [--console|--detach]
                      [--no-dump] [--no-plugin-discovery] [-- [<argument>]...]
 
Options:
        --help, -h  Print the usage info and quit.
        --version, -v
                    Print the version information and quit.
 
        --session, -s <adtfsessionfile>
                    Specify the ADTF Session. Cannot be used in conjuction with --system.
 
        --system <adtfsystemfile>
                    Specify the ADTF System. Cannot be used in conjuction with --session.
 
        --system-properties <adtfpropertiesfile>
                    Specify the ADTF System properties file.
 
        --graph <adtfgraphfile>
                    Specify the ADTF graph file.
 
        --graph-properties <adtfpropertiesfile>
                    Specify the ADTF graph properties file. Requires --graph.
 
        --active-streaming-graph <graphname>
                    Specify the active streaminggraph.
 
        --active-filter-graph <graphname>
                    Set the active filter graph. Overwrite active filter graph settings if existant.
                    Requires --session or --graph.
 
        --environment <adtfenvironmentfile>
                    Specify an ADTF environment file that should be loaded. This is used to resolve
                    macros,dependencies and plugins used by the session. Default is
                    adtf.adtfenvironment from the adtf runtime package.
 
        --adtf-core-plugin <adtfcorepluginfile>
                    Specify a dedicated adtf-core-plugin to load. (default is adtf_core.adtfplugin).
 
        --control-url <url>
                    URL that defines where this instance will listen for RPC calls on. Currently
                    supported protocols are 'http'. With 'http' URLs the host part defines the local
                    interface(s) that the server port will be bound to. Default URL is set to
                    'http://localhost:8000').
 
        --create, -c
                    Create current session (change to MRL_FilterGraphConstructed. This means all
                    elements of the filtergraph have been created but not initialized.
 
        --init, -i  Initialize current session (change to RL_FilterGraph if filtergraph exists,
                    otherwise RL_StreamingGraph). This means the application is ready.
 
        --run, -r   Start current session (change to RL_Running). This means the application is
                    running. Note: This is the only valid runlevel where samples can be transmitted!
 
        --continue-execution-in-case-of-error
                    Fallback to the last stable runlevel if a runlevel cannot be reached due to an
                    error.
 
        --quit, -q  Shutdown application after reaching the end of file, the end of a script or
                    after stopping the configuration.
 
        --quit-timeout <seconds>
                    Shutdown the application after the specified amount of time.
 
        --profiler  Enables the profiler.
        --profiler-port <port>
                    Sets the port for the remote connection to the profiler. 0 = no remote
                    profiling, default = 28077.
 
        --profiler-dump-file <filename>
                    Enables profiling right from the start. When ADTF shuts down, profiling data
                    will be dumped to the given file.
 
        --log-file <filename>
                    Writes all stdout output to the given logfile. Already existing files will be
                    overwritten, otherwise new files are created. The stderr output will be written
                    to "<LOGFILE>_stderr.txt". To get both outputs in one file use instead:
                    "adtf_launcher > logfile.txt 2>&1"
 
        --log-processing-interval <microseconds>
                    If not equal zero, log messages will be processed asynchronously at the given
                    interval.
 
        --log-level-stdout <level>
                    The log level limit for writing log entries to stdout (none, error, warning,
                    info, detail, dump, all). default=all.
 
        --log-level-stderr <level>
                    The log level limit for writing log entries to stderr (none, error, warning,
                    info, detail, dump, all). default=none.
 
        --console   Windows only: Forces the launcher to stay attached with console window or to
                    create a new one as needed. This does not affect whether log messages are
                    written to stdout or not. Implied when the output is piped or redirected on the
                    console level. Implied by --quit. Suppresses all modal error dialogs.
 
        --detach    Windows only: Forces the launcher detach from the launching console - if any.
                    Errors are reported as modal dialogs.
 
        --no-dump   Disables the unhandled exception handler for dumpfile creation and forces a
                    debug print.
 
        --no-plugin-discovery
                    Disables the loading of all available plugin descriptions from the environment.
                    This prevents the automatic lookup of required plugins to solely rely on the
                    plugins specified within the system files.
 
        -- <argument>
                    Ignore all following arguments.
 

Basics

The ADTF Launcher starts the ADTF Runtime and therefore the main processing loop of the ADTF System. Typically the ADTF Launcher is given an ADTF Session file (*.adtfsession) at startup time. The ADTF Session file contains references to the data flow configuration, consisting of different types of ADTF Components like Streaming Sources, Filers and Streaming Sinks get bootstraped by the ADTF Runtime. The ADTF Runtime supports several runlevels where ADTF Components can be started:

Runlevel 1: RL_System
Runlevel 2: RL_Session
Runlevel 3: RL_StreamingGraph
Runlevel 4: RL_FilterGraph
Runlevel 5: RL_Running

Please see Session Initialization for more information and granularity about adtf::base::ant::tADTFRunLevel and adtf::base::quiet::IADTFRuntime::tADTFMicroRunLevel.

Without any optional arguments the default runlevel after the launch is RL_System, which means each ADTF Service specified at this runlevel is instantiated. To bring the ADTF System to a different runlevel, have a look at the available options described in the following sections. The runtime provides several default ADTF Components in the RL_System runlevel the programmer can use:

Session Manager
Macro Resolver
Logging System
RPC Object Server Registry
Sample Stream Tracer RPC

Remote API

The functionality of the ADTF Launcher is made available through a remote API. By default the ADTF Launcher opens a RPC Port through which this API can be accessed. The default URL to reach the ADTF System is http://localhost:8000. The ADTF Control is able to control one instance of the ADTF Launcher. If you prefer an alternate UI solution or want to control more instances at once, please refer to the ADTF Configuration Editor (available as standalone adtf_configuration_editor package).

Launch an ADTF Session

The following command starts the runtime, loads an ADTF Graph from the given ADTF Session file and brings the runtime into state RL_Running. The last parameter makes the log messages appear inside the console.

adtf_launcher --session "path/to/session/my_session.adtfsession" --run --console

Keep an ADTF Session running if an error occurs

The following command loads the ADTF Session as the command from above did, but keeps the ADTF Runtime from shutting down if an error occurs. This is accomplished by staying in the runlevel one level below the runlevel where the error occurred. If, in the example command, the Player from the Demo Playback session is missing the ADTFDAT file, the corresponding error would appear in runlevel RL_Running and the runtime would fallback to the runlevel RL_FilterGraph. If an error occurs already in runlevel RL_System, there is no lower runlevel to fallback to, and the system shuts down as it normally would.

adtf_launcher --session "path/to/session/my_session.adtfsession" --run --console --continue-execution-in-case-of-error

Logging to File

By default, ADTF Launcher starts as a background process. This implies that no console output can be displayed to the user. When stdout or stderr streams are needed for some reason, you have to specify the output target as a redirection on command line. If you want to redirect all standard outputs to logfile.txt use:

adtf_launcher ... > logfile.txt

When standard error stream is also needed in the same file use:

adtf_launcher ... > logfile.txt 2>&1

To limit the number of (debug) output data you can specify the minimal log level for stdout, stderr and debug (Visual Studio only) by parameter.

--log-level-stdout=info
--log-level-stderr=error
--log-level-debug=none

In time-sensitive use cases it might be helpful to write log files asynchronously e.g. every 1000 miliseconds, which you could achieve by supplying the --log-processing-interval 1000 parameter. Use the –-console parameters to write all output to the current console. When no console is open a new one is generated.

The –-console parameter is only available on Windows systems. It does not work in combination with redirection.

UI Extension

Basically the ADTF Launcher is just a headless process starting a headless ADTF System. With the Qt5 ADTF XSystem UI Service (from adtf_qt5 package) the functionality of the ADTF System will be extended with a window manager as base for further delivered or custom adtfplugins containing UI widgets for runtime interaction and visualization.

Table of Contents