Best Practice Tooling

Assumptions of this guide

Imagine you have a ready-to-run ADTF Session where everything has already been setup for you by another user. It is very nice that the ADTF tools can interact with each other. You can for example launch an ADTF Session with a single click (or key) from the ADTF Configuration Editor. But keep in mind that there are multiple ways to launch an ADTF Session. This guide will give you hints on what method to use for a given use-case.

Let's say we have following user types or roles within ADTF:

  • Component Developer
  • Session Designer
  • Runtime User
  • The role of the Component Developer is clear: using the ADTF SDK to usually implement an ADTF Component (Filter, Streaming or System Service) - and hopefully some tests as well. After compiling the source code, the ADTF Plugin Description Generator will generate the plugindescription for the adtfplugin (the binary which contains the ADTF Component) to use within the ADTF Configuration Editor. This is the time to open this tool and putting this ADTF Component into an ADTF Graph, which will be used within an ADTF Session. Of course one single person can do both or all user steps, but the scope and role is definetly switching. So here we are talking about a Session Designer who has the job, to configure a launchable ADTF Session. For testing issues, this user will launch the ADTF Session to see how it works - and uses the convenience to launch it directly from ADTF Configuration Editor with the prefered launch option. After everything is fine, the ADTF Session will be stored and can be used by other users, who are interested in the runtime of the ADTF System - let's call them Runtime Users. They do not have to open the ADTF Configuration Editor again, load the ADTF Project with the required ADTF Session and launch it from there - they can launch the ADTF Session directly without any unnecessary steps or overhead.

    These roles are the basis for the following use-cases. Let's have a more detailed look:

    Create or edit ADTF Sessions before launching

    As mentioned before, some user has to design an ADTF Session to launch it later. Best way to do this is using the ADTF Configuration Editor to create an ADTF Graph, define the required dependencies within the ADTF System (which is done mostly automatically) and configure the behaviour by connecting ADTF Components regarding data and control flow, interface bindings and related property set. That's it.

    By the way... did you know since ADTF 3.6.0 you can also execute the ADTF Configuration Editor as a Runtime User, but only in Read-Only Mode to view the ADTF Sessions, ADTF Graphs and properties without edit functionality (this is still part of the Developer License). So these are the restrictions, other functions like launching tools or ADTF Sessions or navigate from Home View will work the same.

    A possible and alternate way will be the headless ADTF Config Tool. This will be recommended in scripting automatization or very small or testing setups without much overhead, as well as for CLI nerds...

    Inspect ADTF Sessions before launching

    If you only want to view how the ADTF Graph is designed, connected and configured, then simply open the ADTF Configuration Editor. And of course use the direct launch options if you want to launch the ADTF Session in addition.

    If you do not require graphical information about ADTF Graph and stuff, then you can use the ADTF Config Tool to receive the property values, ADTF Components and connections. This might be very useful also in scripting setups.

    Adapt ADTF Sessions before launching

    If you have a lot to change or do not know yet, the ADTF Configuration Editor is the best choice. But if you only want to do some basic stuff, like changing properties, connect/disconnect ADTF Components and more, the smaller ADTF Config Tool might be a good solution - especially in headless environments.

    Launch ADTF Sessions

    If you only have to process data and do not have to change, control or anything else, the easiest way is using the ADTF Launcher standalone. This does not mean that data is "only processing" - depends on your setup there might be some user interactions from UI Services defined in your ADTF System - as well as integrated ADTF Session, Player and Recorder control within Qt5 ADTF XSystem UI Service as your main runtime UI window itself.

    Request information from running ADTF Sessions

    The main difference between ADTF Configuration Editor / ADTF Config Tool and ADTF GUI Control / ADTF Control is the first-named are related to configuration time (create, edit or view an ADTF Session / XML files on disk), the second-named are for runtime (launching, connecting or interacting with an ADTF Session / ADTF System instance).

    Besides the separation of tooling for configuration and runtime, the ADTF Configuration Editor implements an RPC client which makes it possible to connect to an ADTF Session - better say the related RPC interface of the ADTF Launcher. If your required information will end in Sample Stream statistics and activities, this will be a good and comfortable choice. Please have a look at Remote connection.

    To receive or watch runtime information of running ADTF instances, e.g. property values, we are talking about using ADTF Control with a powerful set of functionality, especially in scripting automatization. If you prefer some more user interactions, feel free to use ADTF GUI Control, maybe in combination with ADTF Property Editor Tool.

    Adapt ADTF Sessions after launching

    Sometimes it is necessary to make some changes or other interactions during runtime. We recommend the ADTF Control for launching or connecting (attach to an already running ADTF System). If you prefer UI, please refer to ADTF GUI Control in combination with the ADTF Property Editor Tool. But this solution might not be so powerful than the CLI way.

    (Remote) control one or more ADTF Sessions

    If your ADTF Session is not headless-only and includes one or more UI components, it already contains the Qt5 ADTF XSystem UI Service with integrated support to control the ADTF Session as well as Player and Recorder interfaces when available within the ADTF Session.

    Assuming that your use case extends this function set, your ADTF Session contains only headless components or you need to remote control one or more ADTF Session, the ADTF Configuration Editor (with its Remote connection) is a recommended tool to launch, connect, control and visualize some information from one or more running ADTF Sessions - especially in distributed setups.

    In case you just want to control, launch or connect to more than one ADTF instance, the ADTF GUI Control is a very easy and comfortable alternate UI by using tabs for each connected ADTF Session.

    You can use the ADTF Control as well, especially in scripting automatization or to extend both options described before as a kind of shell terminal for the UI tools or of course standalone. Other extended functionality will be provided by ADTF Log View Tool, ADTF Status Monitor or ADTF Property Editor Tool and others which cover your needs.

    Conclusion

    Here is a short summary of our recommendations:

  • We distinguish between tools for configuration time (before launch) and runtime (after launch)
  • Keep in mind that the Remote connection extension will open both worlds for ADTF Configuration Editor
  • The best choice for configuration time is the ADTF Configuration Editor
  • For performing automated changes to an ADTF Session, we recommend the ADTF Config Tool
  • To launch an ADTF Session we recommend using the ADTF Launcher standalone or - if RPC interaction a.k.a. remote control is required - ADTF Control / ADTF GUI Control without opening the ADTF Configuration Editor before and reduce overhead
  • If your ADTF Session contains UI components the Qt5 ADTF XSystem UI Service extends the ADTF Launcher with direct support for controlling the ADTF Session and - if available - Player and Recorder
  • The best solution for a large set of runtime activities will be provided by the ADTF Control including own shell interaction mode
  • It provides also a command interface for scripting automatization
  • To control one or more ADTF Sessions or distributed setups, the ADTF Configuration Editor will offer you the best support
  • The ADTF GUI Control is a comfortable alternate UI for controlling several ADTF instances by switching between tabs for each ADTF Session
  • If not configured as UI Service in the ADTF System, the ADTF Log View Tool (for logging output), the ADTF Status Monitor (resource and kernel information) and the ADTF Property Editor Tool (for property access) are recommended additions for using the ADTF GUI Control / ADTF Configuration Editor
  • Launching from ADTF Configuration Editor is only necessary for development issues or after you have to view or edit ADTF Sessions before launching and to control after
  • Also take a look at

    ... the ADTF Plugin Description Generator is a very important command line tool to generate all meta information about your adtfplugin to use within the ADTF Configuration Editor. We recommend to integrate it in your post build step by using our CMake Macro and never think about using it yourself manually, there is no need for that.

    ... the ADTF Datdump Tool does not have any connection for designing ADTF Sessions or runtime behaviour. It is just a little command line tooling if you want a quick look into an ADTFDAT recording.

    ... the Profiler GUI is a very powerful and helpful UI if you have to inspect perfomance issues within your runtime behaviour and find maybe deadlocks or long running functions. You will love it ! Look at the options and the guide how to use it (e.g. by using a Launcher with enabled profiling), but that's a parallel or post task beside the assumptions of this guide.

    ... the Licenser Tool is one of the most important tools, because you require at least a valid Runtime License. But in almost 99% of all use cases, you will use this tool only once - before all your work with ADTF is starting. Maybe you are working generic on different machines, then simply integrate the request and load or store of license by integrate it into your scripting automatization.

    ... the ADTF DAT Tool is a 3rd party delivery from ADTF File Library and a complete independent task from this behaviour: To import or export data from/to an ADTFDAT File.

    Where to go next?

    Have a look at the Best Practice Session Design to get some advices regarding the design of ADTF Session's.