2. Quick Start

2. Quick Start

Common start pattern

In general, an application which uses the multithreading support of the framework of XCOFDK is required to follow a small pattern of action items:

1. task model:
   define, configure and implement application's task(s) by subclassing MainXTask and/or XTask,
2. launch the framework:
   start the framework using its API of runtime control at a proper place of choice when the application is executed,
3. instantiate and start application's starting task:
   applications may also opt to perform this step before lanunching the framework when the application is started,
4. instantiate and start additional tasks:
   additional tasks may be (dynamically) instantiated and started, too, either just like done in step 3. or later from within any running application task,
5. stop the framework:
   decide where or by when to stop the framework, again using its API of runtime control.
   Normally, this is done when specific application task(s), e.g the main task, finish their execution.
   Note that stopping the framework is a mandatory, non-blocking request to the framework to stop all tasks still running,
6. wait for framework's termination:
   blocking wait for the framework to complete its coordinated shutdown.
   Usually this is done right before the program termination takes place.

Console program quickStart.py

The console application quickStart.py demonstrates typical use of the framework following abovementioned action items:

• a quite simple task model consisting of the starting task only, that is an instance of either AppMainTask or AppTask,
• termination of the starting task is chosen as synchronization point at which the framework is instructed to stop.

The output of the program is shown in section Program output below. To demonstrate most common start scenarios, the program provides a few optional command line arguments:

• --use-sync-task:
  make application's starting task _myTsk is configured to be a synchronous task.
  Otherwise, the starting task will be an asynchronous task executed in a separate, new host, i.e. Python, thread,
• --no-main-task:
  make application's starting task _myTsk is an instance of class AppTask, instead of class AppMainTask.
  Note that task classes derived from MainXTask always have a singleton instance only, designed to represent application's main task,
• --disable-log-timestamp:
  framework start option to disable/hide the timestamp of user log entries,
• --disable-log-highlighting:
  framework start option to disable color highlighting of log entries.

NOTE:
The starting task of GUI applications supported by the framework, e.g. programs using tkinter, might
work the best if represented by application's main task with synchronous execution type. This is especially
true if the underlying GUI framework is not capable of multithreading.

# file : quickStart.py

import sys
from   threading import current_thread as _PyCurThread  # for demonstration purposes only

from xcofdk             import fwapi
from xcofdk.fwcom       import ETernaryCallbackResultID
from xcofdk.fwcom       import override
from xcofdk.fwcom       import xlogif
from xcofdk.fwapi.xtask import XTask
from xcofdk.fwapi.xtask import MainXTask
from xcofdk.fwapi.xtask import XTaskProfile

class AppMainTask(MainXTask):
    def __init__(self, bSynchronousTask_ =True):
        if bSynchronousTask_: _tp = XTaskProfile.CreateSynchronousTaskProfile(aliasName_='appMainTask')
        else:                 _tp = XTaskProfile.CreateAsynchronousTaskProfile(aliasName_='appMainTask')
        MainXTask.__init__(self, taskProfile_=_tp)

    @override
    def RunXTask(self) -> ETernaryCallbackResultID:
        _msg  = 'sync.' if self.xtaskProfile.isSynchronousTask else 'async.'
        _msg  = f'Welcome to XCOFDK by {_msg} {self.xtaskAliasName}:'
        _msg += f'\n\tcurrent host thread : {_PyCurThread().name}'
        xlogif.LogInfo(_msg)
        return ETernaryCallbackResultID.STOP

class AppTask(XTask):
    def __init__(self, bSynchronousTask_ =False):
        if bSynchronousTask_: _tp = XTaskProfile.CreateSynchronousTaskProfile(aliasName_='appTask')
        else:                 _tp = XTaskProfile.CreateAsynchronousTaskProfile(aliasName_='appTask')
        XTask.__init__(self, taskProfile_=_tp)

    @override
    def RunXTask(self) -> ETernaryCallbackResultID:
        _msg  = 'sync.' if self.xtaskProfile.isSynchronousTask else 'async.'
        _msg  = f'Welcome to XCOFDK by {_msg} {self.xtaskAliasName}:'
        _msg += f'\n\tcurrent host thread : {_PyCurThread().name}'
        xlogif.LogInfo(_msg)
        return ETernaryCallbackResultID.STOP

def Main(bSyncTask_ =False, bUseMainTask_ =True, fwStartOptions_ : list =None):
    if not fwapi.StartXcoFW(fwStartOptions_=fwStartOptions_):  # step 1: start the framework
        return 71                                              #
    if bUseMainTask_:                                          # step 2: create application's starting task
        _myTsk = AppMainTask(bSynchronousTask_=bSyncTask_)     #
    else:                                                      #
        _myTsk = AppTask(bSynchronousTask_=bSyncTask_)         #
                                                               #
    _myTsk.Start()                                             # step 3: start the starting task
    _myTsk.Join()                                              # step 4: wait for starting task's termination
                                                               #
    fwapi.StopXcoFW()                                          # step 5: stop the framework
    _bLcErrorFree = fwapi.JoinXcoFW()                          # step 6: wait for framework's coordinated shutdown
                                                               #
    res = 72 if not _bLcErrorFree else 0                       # step 7: check for LC failure (if any)
    return res

def _ScanCmdLine():
    _lstFW_START_OPTIONS    = [ '--disable-log-timestamp' , '--disable-log-highlighting' ]
    _lstQUICK_START_OPTIONS = [ '--use-sync-task', '--no-main-task' ]

    _bSync, _bMain, _lstOptions = False, True, []
    for aa in sys.argv:
        if aa in _lstFW_START_OPTIONS: _lstOptions.append(aa)
            continue
        if aa in _lstQUICK_START_OPTIONS:
            if _lstQUICK_START_OPTIONS.index(aa) == 0: _bSync = True
            else: _bMain = False
            continue
    return _bSync, _bMain, _lstOptions

if __name__ == "__main__":
    _bSyncTask, _bUseMainTask, _lstStartOptions = _ScanCmdLine()
    exit(Main(bSyncTask_=_bSyncTask, bUseMainTask_=_bUseMainTask, fwStartOptions_=_lstStartOptions))

---

[Top]

Program output

The output of the program should look like below:

• if executed with below command line argument(s) supplied:

  $> python3.12 -m quickStart --use-sync-task

  

• if executed with below command line argument(s) supplied:

  $> python3.12 -m quickStart --no-main-task

  

---

[Top] [Home] [Previous] [Next] - [1. Introduction] [3. API Documentation] [4. At a Glance] [5. Basic Examples]