Metadata-Version: 2.4
Name: xcofdk
Version: 4.0
Summary: XCOFDK is a runtime environment to provide multithreading, multiprocessing and life cycle management to programs.
Author-email: Farzad Safa <farzad.safa@xcofdk.com>
License-Expression: LicenseRef-XCOFDK-License-1.0
Project-URL: Homepage, https://github.com/xcofdk/xcofdk-py/
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Free Threading :: 3 - Stable
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: xcofdk-rte
Dynamic: license-file

<!-- ---------------------------------------------------------------------------
File        : README.md
Copyright(c) 2023-2026 Farzad Safa (farzad.safa@xcofdk.com)

This file is distributed under the same license provided through the SOFTWARE it is part of.
A copy of the license file can also be obtained following the link below:
    https://github.com/xcofdk/xcofdk-py/blob/master/LICENSE.txt
------------------------------------------------------------------------------->


<!-- add-badges-to-readme
![Auto Assign](https://github.com/xcofdk/xcofdkrte-py/actions/workflows/auto-assign.yml/badge.svg)

![Proof HTML](https://github.com/xcofdk/xcofdkrte-py/actions/workflows/proof-html.yml/badge.svg)
-->


# Project Description

**XCOFDK** is the architecture of an e**X**tensible, **C**ustomizable and **O**bject-oriented **F**ramework 
**D**evelopment **K**it.

This project presents an implementation of the <u>default frontend package</u> of XCOFDK for Python through the PyPI 
package [xcofdk](https://pypi.org/project/xcofdk/). <br> 
It uses XCOFDK's backend package [xcofdk-rte](https://pypi.org/project/xcofdk-rte/) which is responsible for providing 
the runtime environment (RTE) of the framework. <br> 
As a result, it provides Python applications with a runtime environment capable of:  
- stable and reliable execution at any time,
- running active services responsible for life-cycle management,
- managed, unified error handling,
- parallel or concurrent processing out-of-the-box,
- instant access for transparent task or process communication,
- supporting free-threaded (FT) Python (starting with the stable Python version <tt>3.14.0</tt>), 
- providing API for auxiliary, bundled services commonly expected for application developement. 

<br>


# Installation

XCOFDK is available for **Python versions 3.11+** on both POSIX and Windows platfroms.

> **NOTE:** <br>
> - By installing you agree to the terms and conditions of use of the software (see section [Licensing](#licensing) below). 

<br> 

Install using PyPI package [xcofdk](https://pypi.org/project/xcofdk/) (with PyPI package [xcofdk-rte](https://pypi.org/project/xcofdk-rte/) is auto-installed if not done yet):

```bash
$> python3 -m pip install xcofdk
```

<br>


# Quick Start

In general, the [runtime environment RTE](https://github.com/xcofdk/xcofdk-py/wiki/3.-Architecture#33-runtime-environment-rte) 
of the framework of [XCOFDK for Python](https://github.com/xcofdk/xcofdk-py) is responsible for the complete execution 
of (part of) the task model of a program which uses the 
[multithreading subsystem](https://github.com/xcofdk/xcofdk-py/wiki/4.-API-Overview#43-xmt---subsystem-multithreading) 
of XCOFDK to construct that (part of the) task model. As such and except for the traditional <tt>'Hello world!'</tt>, 
any possible quick-start and sample porgram is by definition more than a 2-liner, especially when demonstrating some 
major aspects in practice.

Hence, the console program [quickStart.py](https://github.com/xcofdk/xcofdk-py/blob/master/xexamples/xuserapp/basic/xmt/rc/quickStart.py) 
demonstrates (partly advanced) use of the framework illustrating many of framework's features available for 
applications developed for multitasking. The task model of <tt>quickStart.py</tt> is composed of task instances designed for 
*rapid construction (RC)* by passing a (regular) callback function to the contructor of the respective class: 
- a [message-driven server task](https://github.com/xcofdk/xcofdk-py/wiki/2.-Quick-Start#24-algoservercbtgt), an 
  instance of class [MessageDrivenTask](https://github.com/xcofdk/xcofdk-py/blob/master/src/xcofdk/fwapi/xmt/rctask.py),
- a few [asynchronous client tasks](https://github.com/xcofdk/xcofdk-py/wiki/2.-Quick-Start#25-algoclientcbtgt), 
  instances of class [AsyncTask](https://github.com/xcofdk/xcofdk-py/blob/master/src/xcofdk/fwapi/xmt/rctask.py), 
- an [(a)synchronous starter (or main) task](https://github.com/xcofdk/xcofdk-py/wiki/2.-Quick-Start#26-startertaskcbtgt), 
  an instance of class [AsyncTask](https://github.com/xcofdk/xcofdk-py/blob/master/src/xcofdk/fwapi/xmt/rctask.py) 
  or [SyncTask](https://github.com/xcofdk/xcofdk-py/blob/master/src/xcofdk/fwapi/xmt/rctask.py). 

The above-mentioned [RC task classes](4.-API-Overview#431-task-classes) are each an implementation of the interface 
class [IRCTask](https://github.com/xcofdk/xcofdkrte-py/blob/master/src/xcofdkrte/api/apiif/std/ifrctask.py) or 
[IRCCommTask](https://github.com/xcofdk/xcofdkrte-py/blob/master/src/xcofdkrte/api/apiif/std/ifrctask.py), respectively. 


## Program Purpose

The application is designed to provide the execution of a given algorithm, here 
[CartProdAlgo](https://github.com/xcofdk/xcofdk-py/blob/master/xexamples/xuserapp/util/userAppUtil.py), 
several times using both multithreading and multiprocessing. Each time an execution is requested, the algorithm 
constructs a random **Cartesian Product (CP)** and properly returns the result to the requestor, which is either an 
application (client) task or a child process. 

The output of the program is as shown below: 
- with the command line option for small CPs supplied:
  ```ascii
  $> python3 -m quickStart --small-cartesian-product
  ...
  [10:51:39.774 XINF][MainThread] Welcome to XCOFDK in TerminalMode of RTE.
  [10:51:39.777 XINF][Tsk_501002] Running async. MainTask, current host thread: Tsk_501002
  [10:51:39.784 XINF][Tsk_501002] Starting 5x child processes...
  [10:51:39.794 XINF][CTsk_501001] Task AlgoSrv received first delivered message.
  [10:51:39.833 XINF][Tsk_501002] Starting 5x async. algo-client tasks...
  [10:51:40.982 XINF][CTsk_501001] Put request to stop the framework.
  [10:51:41.239 XINF] Got total of 29x small CartProdAlgo executions:
	  [10:51:39.795][TID:501001:AlgoSrv]  digitSet='554346'   size=7776     tail:   66665 ,  66664 ,  66663 ,  66664 ,  66666
	  [10:51:39.796][TID:501002]          digitSet='096563'   size=7776     tail:   33339 ,  33336 ,  33335 ,  33336 ,  33333
	  [10:51:39.847][TID:501003]          digitSet='431343'   size=7776     tail:   33333 ,  33331 ,  33333 ,  33334 ,  33333
	  [10:51:39.848][TID:501004:AlgoC_4]  digitSet='650890'   size=7776     tail:   00005 ,  00000 ,  00008 ,  00009 ,  00000
	  [10:51:39.853][TID:501006:AlgoC_6]  digitSet='319215'   size=7776     tail:   55551 ,  55559 ,  55552 ,  55551 ,  55555
	  [10:51:39.859][TID:501003:AlgoC_3]  digitSet='009382'   size=7776     tail:   22220 ,  22229 ,  22223 ,  22228 ,  22222
	  [10:51:39.869][TID:501005]          digitSet='592380'   size=7776     tail:   00009 ,  00002 ,  00003 ,  00008 ,  00000
	  [10:51:39.870][TID:501007]          digitSet='880532'   size=7776     tail:   22228 ,  22220 ,  22225 ,  22223 ,  22222
	  [10:51:39.892][TID:501003]          digitSet='436662'   size=7776     tail:   22223 ,  22226 ,  22226 ,  22226 ,  22222
	  [10:51:39.893][TID:501004]          digitSet='537849'   size=7776     tail:   99993 ,  99997 ,  99998 ,  99994 ,  99999
	  [10:51:39.903][TID:501003:AlgoC_3]  digitSet='580180'   size=7776     tail:   00008 ,  00000 ,  00001 ,  00008 ,  00000
	  [10:51:39.914][TID:501005:AlgoC_5]  digitSet='637946'   size=7776     tail:   66663 ,  66667 ,  66669 ,  66664 ,  66666
	  [10:51:39.933][TID:501004:AlgoC_4]  digitSet='277872'   size=7776     tail:   22227 ,  22227 ,  22228 ,  22227 ,  22222
	  [10:51:39.956][TID:501006]          digitSet='758336'   size=7776     tail:   66665 ,  66668 ,  66663 ,  66663 ,  66666
	  [10:51:39.957][TID:501007:AlgoC_7]  digitSet='981034'   size=7776     tail:   44448 ,  44441 ,  44440 ,  44443 ,  44444
	  [10:51:39.978][TID:501004]          digitSet='184398'   size=7776     tail:   88888 ,  88884 ,  88883 ,  88889 ,  88888
	  [10:51:39.981][TID:501005]          digitSet='934481'   size=7776     tail:   11113 ,  11114 ,  11114 ,  11118 ,  11111
	  [10:51:40.017][TID:501006:AlgoC_6]  digitSet='760015'   size=7776     tail:   55556 ,  55550 ,  55550 ,  55551 ,  55555
	  [10:51:40.038][TID:501005:AlgoC_5]  digitSet='785376'   size=7776     tail:   66668 ,  66665 ,  66663 ,  66667 ,  66666
	  [10:51:40.064][TID:501007]          digitSet='569537'   size=7776     tail:   77776 ,  77779 ,  77775 ,  77773 ,  77777
	  [10:51:40.106][TID:501006]          digitSet='121922'   size=7776     tail:   22222 ,  22221 ,  22229 ,  22222 ,  22222
	  [10:51:40.161][TID:501007:AlgoC_7]  digitSet='360856'   size=7776     tail:   66666 ,  66660 ,  66668 ,  66665 ,  66666
	  [10:51:40.373][TID:501002]          digitSet='675160'   size=7776     tail:   00007 ,  00005 ,  00001 ,  00006 ,  00000
	  [10:51:40.374][TID:501001:AlgoSrv]  digitSet='172422'   size=7776     tail:   22227 ,  22222 ,  22224 ,  22222 ,  22222
	  [10:51:40.886][PID:8925]            digitSet='10090759' size=2097152  tail:  9999999 , 9999990 , 9999997 , 9999995 , 9999999
	  [10:51:40.917][PID:8924]            digitSet='46547588' size=2097152  tail:  8888884 , 8888887 , 8888885 , 8888888 , 8888888
	  [10:51:40.939][PID:8923]            digitSet='85952934' size=2097152  tail:  4444445 , 4444442 , 4444449 , 4444443 , 4444444
	  [10:51:40.939][PID:8922]            digitSet='39827680' size=2097152  tail:  0000002 , 0000007 , 0000006 , 0000008 , 0000000
	  [10:51:40.941][PID:8926]            digitSet='61406133' size=2097152  tail:  3333330 , 3333336 , 3333331 , 3333333 , 3333333
  [10:51:41.240 XINF] Done, elapsed time for small CartProdAlgo: 0:00:01.808899
  ```
- lines with **<tt>[TID:nnnn]</tt>** inside are each the CP result of a request made by or on behalf of an application (client) task,
- lines with **<tt>[PID:nnnn]</tt>** inside are each the CP result of a request made out of a child process.


## Main Function

The module function [Main()](https://github.com/xcofdk/xcofdk-py/blob/master/xexamples/xuserapp/basic/xmt/rc/quickStart.py) 
represents program's entry point which is basically organized in accordance to the 
[common pattern of use](4.-API-Overview#4511-common-pattern-of-use) of the framework. When called, it performs below 
activities:
- **step 1:** [configuration of framework's RTE](4.-API-Overview#442-rte-configuration-api) depending on the supplied command line options (if any):
  - enable RTE policy for [TerminalMode](https://github.com/xcofdk/xcofdkrte-py/blob/master/src/xcofdkrte/api/cdefs/std/fwdefs.py), 
- **step 2:** [start of the framework](4.-API-Overview#4512-control-functions), 
- **step 3:** create and start application's [message-driven server task](#24-algoservercbtgt) which will be responsible for: 
  - triggering new CP calculations on behalf of application (client) tasks the server receives request messages from, 
  - managing the <tt>TerminalMode</tt> (if enabled):
    - wait for running child processes (if any) to complete, 
    - leave the <tt>TerminalMode</tt> by putting a [stop request to the framework](4.-API-Overview#4512-control-functions), 
- **step 4:** create and start application's [starter task](#26-startertaskcbtgt), responsible for: 
  - start of both child processes and client tasks,
  - wait for client tasks to complete,
  - request the server task to quit, 
- **step 5:** if the RTE policy <tt>TerminalMode</tt> is disabled: 
  - wait for running child processes (if any) to complete, 
- **step 6:** wait for [framework's coordinated shutdown](4.-API-Overview#4512-control-functions): 
  - if the RTE policy <tt>TerminalMode</tt> is enabled, then the framework will wait before entering its shutdown sequence <br> 
    as long as the <tt>TerminalMode</tt> is not left (see step 3 above), 
  - otherwise it will wait as long as there are application tasks still running (see RTE policy 
    [AutoStop](https://github.com/xcofdk/xcofdkrte-py/blob/master/src/xcofdkrte/api/cdefs/std/fwdefs.py)),
- **step 7:** collect and put out the CP results.

<br>

```python
def Main(cmdLineOpts_ : CLOptions):
    _startTime = datetime.now()

    # step 1: configure framework's RTE for terminal mode
    if cmdLineOpts_.isSmallCartProdEnabled:
        DisableBigCartProd()
        rtecfg.RtePolicyEnableTerminalMode()

    # step 2: start framework
    if not fwapi.StartXcoFW(fwStartOptions_=cmdLineOpts_.GetSuppliedFwOptions()):
        return 71

    # step 3: create and start appplication's algo-server task
    _algoSrv = MessageDrivenTask(AlgoServerCBTgt, aliasName_='AlgoSrv', bRefToCurTaskRequired_=True, pollingFrequency_=20)
    _algoSrv.Start()

    # step 4: create and start appplication's starter task
    #         (which will create and start both child processes and client tasks, too)
    _count, _procPool = 5, []
    _starterTsk = CreateStartStarterTask(cmdLineOpts_, _algoSrv.taskUID, _count, _procPool)

    # step 5: if not in terminal mode, wait for running child processes to complete
    if not rtecfg.RtePolicyGetConfig().isTerminalModeEnabled:
        fwapi.JoinProcesses()

    # step 6: wait for framework's coordinated shutdown
    _bLcErrorFree = fwapi.JoinXcoFW()

    # step 7: collect and print out results of CP requests executed
    if _bLcErrorFree:
        _procPoolRes = [_pp.processSuppliedData for _pp in _procPool if _pp.processSuppliedData is not None]
        #...
        xlogif.LogInfo(f'Done, elapsed time for {_msg1} CartProdAlgo: ' + str(datetime.now()-_startTime))

    # done: check for LC failure (if any)
    res = 72 if not _bLcErrorFree else 0
    return res
```

<br>

More introductory information relared to [XCOFDK for Python](https://github.com/xcofdk/xcofdk-py) available on the 
wiki pages below: 
- [1.4 Public API and User Applications](https://github.com/xcofdk/xcofdk-py/wiki/1.-Introduction#14-public-api-and-user-applications) 
  focusing on the use of the API by user programs, 
- [2. Quick Start](https://github.com/xcofdk/xcofdk-py/wiki/2.-Quick-Start) explaining the above console program 
  in more detail: 
  - [2.2 Import of the API](https://github.com/xcofdk/xcofdk-py/wiki/2.-Quick-Start#22-import-of-the-api)
  - [2.4 AlgoServerCBTgt()](https://github.com/xcofdk/xcofdk-py/wiki/2.-Quick-Start#24-algoservercbtgt)
  - [2.5 AlgoClientCBTgt()](https://github.com/xcofdk/xcofdk-py/wiki/2.-Quick-Start#25-algoclientcbtgt)
  - [2.6 StarterTaskCBTgt()](https://github.com/xcofdk/xcofdk-py/wiki/2.-Quick-Start#26-startertaskcbtgt)
  - [2.7.1 CreateStartStarterTask()](https://github.com/xcofdk/xcofdk-py/wiki/2.-Quick-Start#271-createstartstartertask)
  - [2.7.2 CreateStartAlgoProcesses()](https://github.com/xcofdk/xcofdk-py/wiki/2.-Quick-Start#272-createstartalgoprocesses)
  - [2.7.3 CreateStartAlgoClients()](https://github.com/xcofdk/xcofdk-py/wiki/2.-Quick-Start#273-createstartalgoclients)
- [3. Architecture](https://github.com/xcofdk/xcofdk-py/wiki/3.-Architecture) for the design and subsystems of the 
  framework,
- [4. API Overview](https://github.com/xcofdk/xcofdk-py/wiki/4.-API-Overview) for an overview of the API of the framework, 
- [5. Basic Examples](https://github.com/xcofdk/xcofdk-py/wiki/5.-Basic-Examples) for introductory examples of 
  (real-world) programs using the framework. <br> 
  Note that most of the examples are applications developed using GUI framework [tkinter](https://docs.python.org/3/library/tkinter.html). 

<br>

# Licensing

Use of the default frontend package [xcofdk](https://pypi.org/project/xcofdk/) is free of charge and granted under 
terms and conditions stated in the [License](https://github.com/xcofdk/xcofdk-py/blob/master/LICENSE.txt) file. 

<br>

# Links

<!-- below html-style is working in VS Code only, but not for PyPI or GitHub  !!
<style>
td, th {
   border: none!important;
}
</style>
-->

| Main page            | :      | [XCOFDK on GitHub](https://github.com/xcofdk/xcofdk-py)                                                                                                                                                                                 |
| -------------------  | -----  |----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------             |
| **Wiki**             | **:**  | [**XCOFDK Wiki**](https://github.com/xcofdk/xcofdk-py/wiki)                                                                                                                                                                             |
| **API**              | **:**  | [**API Overview**](https://github.com/xcofdk/xcofdk-py/wiki/4.-API-Overview)                                                                                                                                                            |
| **Examples**         | **:**  | [**xcofdk-py-examples.tar.gz**](https://github.com/xcofdk/xcofdk-py/blob/master/xexamples/xcofdk-py-examples.tar.gz) \| [**xcofdk-py-examples.zip**](https://github.com/xcofdk/xcofdk-py/blob/master/xexamples/xcofdk-py-examples.zip)  |
| **Changelog**        | **:**  | [**Release highlights & release notes**](https://github.com/xcofdk/xcofdk-py/blob/master/doc/release_notes.md#release-highlights-v40)                                                                                                   |
| **License file**     | **:**  | [**License**](https://github.com/xcofdk/xcofdk-py/blob/master/LICENSE.txt)                                                                                                                                                              |
| **Support**          | **:**  | **support@xcofdk.com**                                                                                                                                                                                                                  |
| **Error reporting**  | **:**  | **error-xpy@xcofdk.com**                                                                                                                                                                                                                |
