AREG SDK

AREG is an asynchronous Object RPC framework to simplify multitasking programming by blurring borders between processes and treating remote objects as if they coexist in the same thread.

Description

AREG SDK is an interface-centric real-time asynchronous communication engine to enable distributed- and mist-computing, where connected Things interact and provide services as if they act like thin distributed servers. The communication engine of AREG SDK is based on Object Remote Procedure Call (ORPC) protocol.

Programming language: C++

License: Apache License 2.0

Tags: Frameworks     Inter-process Communication     Windows     Linux     Cross-platform     Rpc     Library     IPC     C++17    

README

AREG SDK

The latest development sources can be cloned from 20220701-candidate branch. Please check the branch build status before using it.

---

<!-- markdownlint-disable -->

Project Status[](./docs/img/pin.svg)

---

Introduction[](./docs/img/pin.svg)

AREG SDK is a developer-friendly, interface-centric real-time asynchronous communication engine to enable distributed- and mist-computing, where connected Things interact and provide services as if they act like thin distributed servers.

---

Table of contents[](./docs/img/pin.svg)

1. Motivation
2. More than embedded
3. Flexible and self-sufficient
4. Composition
5. Software build
6. Software integration
   • Multicast router
   • Logging service
   • Development
7. Use cases and benefits
   • Distributes solutions
   • Driverless devices
   • Real-time solutions
   • Digital twin
   • Simulation and test automations
8. Examples
9. Licensing
10. Call for action

---

Motivation[](./docs/img/pin.svg)

Traditionally, devices are connected to clients to stream data to the cloud or fog servers for further processing. Since data is generated and collected at the edge of the network (mist network), it makes sense to change the role of connected Things and provide network-accessible (Public) services directly on devices. This extends Cloud to the extreme edge and it is a good foothold for robust solutions such as:

• Increase data privacy, which is an important factor for sensitive data.
• Decrease data streaming, which is a fundamental condition to optimize network communication.
• Develop autonomous, intelligent and self-aware devices by providing network services directly in the environment of data origin.

[ ↑ to top ↑ ]

---

More than embedded[](./docs/img/pin.svg)

When we were designing AREG SDK, the guiding principle was to provide a homogeneous solution for Multithreading, Multiprocessing and Internet communication wrapped in services appropriately having Local, Public and Internet categories. These services are neither processes nor tasks managed by the operating system, they are software components with a predefined interface, in which methods are invoked remotely.

💡 In current version, the AREG engine handles multithreading (Local) and multiprocessing (Public) communication.

The AREG engine forms a fault-tolerant system, automatically discovers services, automates communication, simplifies distributed programming, and helps developers to focus on application business logic as if they would program a single process application with one thread where methods of objects are event-driven. The engine guarantees that:

• The crash of one application does not cause the crash of the system.
• The service clients are automatically notified about service availability status.
• The client requests are automatically invoked to run on the service component.
• The service responses are automatically invoked on the exact client, and they are not mixed or missed.
• The subscriptions on data, responses and broadcasts are automatically invoked on the client when service triggers a call.

[ ↑ to top ↑ ]

---

Flexible and self-sufficient[](./docs/img/pin.svg)

AREG SDK is ideal to develop multiprocessing and multithreading Desktop and/or Embedded applications. The interface-centric solution of AREG framework includes all features of action-centric (Request-Reply) and data-centric (Publisher-Subscriber) solutions:

• The request and response mechanisms are as simple as calling an ordinary method of an object.
• The subscriptions are dynamic and the latest data is delivered immediately after subscribing.
• Clients may subscribe and unsubscribe on data and events at any time during runtime.

The framework ensures to keep applications modular, where components communicate via predefined Service Interfaces, which are invoked in the thread-safe environment. It easily handles cross-dependencies, where applications do not need to have special startup sequences and priorities.

💡 The [examples](./examples) of AREG SDK contain multiple projects to check the features and fault tolerant behavior of AREG communication engine.

[ ↑ to top ↑ ]

---

Composition[](./docs/img/pin.svg)

AREG SDK consists of:

1. [Multicast router (mcrouter)](./framework/mcrouter/) to use for IPC. It runs either as a service managed by the OS or as a console application.
2. [AREG framework (or engine)](./framework/areg/) is a library (shared or static) linked in every application.
3. [Code generator tool](./tools/) to create client and server base objects from a service prototype document.

The framework contains a dynamic and configurable logging service. More tools and features are planned for future releases.

[ ↑ to top ↑ ]

---

Software build[](./docs/img/pin.svg)

An example to get source codes and compile under Linux. You'd need at least C++17 g++ (default) compiler. Open Terminal console in your projects folder and take the following steps:

To build the project using cmake

# Step 1: Get sources from GitHub
$ git clone https://github.com/aregtech/areg-sdk.git
$ cd areg-sdk

# Step 2: Create a subdirectory for CMake cache files and change directory to it.
$ mkdir build && cd build

# Step 3: Initialize CMake cache and build systems configuration.
#         Enable examples compilation by using BUILD_EXAMPLES flag.
$ cmake .. -DBUILD_EXAMPLES=ON

# Step 4: Compile sources by calling: cmake --build [CMake cache dir] <optional> -j [concurrent jobs]
$ cmake --build . -j 8

To build the project using make

# Step 1: Get sources from GitHub
$ git clone https://github.com/aregtech/areg-sdk.git
$ cd areg-sdk

# Step 2: Compile sources from terminal by calling: make [all] [framework] [examples]
$ make

After compilation, the binaries are located in <areg-sdk>/product/build/<compiler-platform-path>/bin folder.

AREG SDK sources are developed for: Supported OS Linux (list of POSIX API), Windows 8 and higher. Supported CPU x86, x86_64, arm and aarch64. Supported compilers Version C++17 GCC, g++, clang and MSVC.

💡 The other POSIX-compliant OS and compilers are not tested yet.

Compile AREG SDK sources and examples: | Solution | Platforms | API | Quick actions to compile | | --- | --- | --- | --- | | CMakeLists.txt | Linux, Windows | POSIX, Win32 | It is used to compile applications using following tools:    - call cmake in command line;    - configure and build in Visual Studio Code IDE;    - build in Microsoft Visual Studio IDE (VS2019 and higher). | | Makefile | Linux| POSIX | It is used to compile application by calling make in command line. | | areg-sdk.sln | Windows | Win32 | It is used to make a build in Microsof Visual Studio IDE (VS2019 and higher). | | .project | Linux, Windows | POSIX | To import and build projects in Eclipes IDE. |

💡 Compilation with Eclipse under Windows platform might require to switch the Toolchain. For example, Cygwin GCC. 💡 For Linux platform the default compiler is g++. To change the compiler to build with:

• cmake, update [conf/cmake/pre-project.cmake](./conf/cmake/pre-project.cmake) file. For example, set(CMAKE_CXX_COMPILER /usr/bin/g++-4.2)
• make, update [conf/make/user.mk](./conf/make/user.mk) file. For example, Toolset := clang++-13.

Details on how to change compiler, load and compile sources for various targets are described in [HOWTO](./docs/HOWTO.md).

[ ↑ to top ↑ ]

---

Software integration[](./docs/img/pin.svg)

Multicast router

Configure [router.init](./framework/areg/resources/router.init) file to set the IP-address and the port of multicast router:

connection.address.tcpip    = 127.0.0.1 # the address of mcrouter host
connection.port.tcpip       = 8181      # the connection port of mcrouter

The multicast router forms the network and can run on any device. For example, in case of M2M communication, it can run on a gateway, in case of IPC, it can run on the same machine. In case of multithreading application development, there is no need to configure router.init and run mcrouter.

Logging service

Configure [log.init](./framework/areg/resources/log.init) to set scopes, log priorities and log file name:

log.file        = %home%/logs/%appname%_%time%.log # create logs in 'log' subfolder of user home 
scope.mcrouter.*= NOTSET ;                         # disable logs for mcrouter.

scope.my_app.*                   = DEBUG | SCOPE ; # enable all logs of my_app
scope.my_app.ignore_this_scope   = NOTSET ;        # disable logs of certain scopes in my_app
scope.my_app.ignore_this_group_* = NOTSET ;        # disable logs of certain scope group in my_app

💡 By default, the router.init and log.init files are located in the config subfolder of binaries. 💡 To enable all logs of all applications, use scope.* = DEBUG | SCOPE ; . 💡 In the current version the logging is possible only in file.

Development

The development guidance and step-by-step example to create a simple service-enabled application are described in [DEVELOP](./docs/DEVELOP.md).

[ ↑ to top ↑ ]

---

Use cases and benefits[](./docs/img/pin.svg)

AREG SDK can be used in a very large scope of multithreading and multiprocessing application development running on Linux or Windows machines.

Distributed solution

AREG SDK is a distributed computing solution, where the services can be distributed and run on any node of the network. The automatic service discovery makes service location transparent, so that the applications interact as if the components are located in one process. Developers define a model, which is a description of service relationship, and load it to start services during runtime. The services can easily be distributed between multiple processes.

The following is a demonstration of a static model description, which is loaded to start services and unloaded to stop them.

// main.cpp source file.

// Defines static model with 2 services
BEGIN_MODEL(NECommon::ModelName)

    BEGIN_REGISTER_THREAD( "Thread1" )
        BEGIN_REGISTER_COMPONENT( "RemoteRegistry", RemoteRegistryService )
            REGISTER_IMPLEMENT_SERVICE( NERemoteRegistry::ServiceName, NERemoteRegistry::InterfaceVersion )
        END_REGISTER_COMPONENT( "RemoteRegistry" )
    END_REGISTER_THREAD( "Thread1" )

    BEGIN_REGISTER_THREAD( "Thread2" )
        BEGIN_REGISTER_COMPONENT( "SystemShutdown", SystemShutdownService )
            REGISTER_IMPLEMENT_SERVICE( NESystemShutdown::ServiceName, NESystemShutdown::InterfaceVersion )
        END_REGISTER_COMPONENT( "SystemShutdown" )
    END_REGISTER_THREAD( "Thread2" )

END_MODEL(NECommon::ModelName)

// the main function
int main()
{
    // Initialize application, enable logging, servicing, routing, timer and watchdog.
    // Use default settings.
    Application::initApplication( );

    // load model to start service components
    Application::loadModel(NECommon::ModelName);

    // wait until Application quit signal is set.
    Application::waitAppQuit(NECommon::WAIT_INFINITE);

    // stop and unload service components
    Application::unloadModel(NECommon::ModelName);

    // release and cleanup resources of application.
    Application::releaseApplication();

    return 0;
}

In the example, the "RemoveRegistry" and the "SystemShudown" are the names of components called roles, and the NERemoteRegistry::ServiceName and the NESystemShutdown::ServiceName are the interface names. In combination, they define the service name used to access in the network. These MACRO create static model NECommon::ModelName, which is loaded when call Application::loadModel(NECommon::ModelName), and the services are stopped when call Application::unloadModel(NECommon::ModelName).

In this example, services can be merged in one thread or distributed in 2 processes by defining a model in each process. Independent on service location, neither software developers, nor service client objects feel a difference except for possible slight network latency when running IPC. The services must have unique names within the scope of visibility. Means, in case of Public services, the names are unique within a network, and in case of Local services, the names are unique within a process scope. An example of developing a service and a client in one and multiple processes is in [Hello Service!](./docs/DEVELOP.md#hello-service) project described in the development guide.

Driverless devices

Normally, the devices are supplied with the drivers to install in the system and with the header files to integrate in the application(s). The drivers often run in Kernel mode and the crash of the driver crashes the entire system. Driver development requires a special technique, which is different for each operating system, and it is hard to debug. Our proposal is to deliver driverless service-enabled devices, where device-specific services are described in the interface prototype documents. In contrast to drivers, the service development does not differ from user mode application development, it is faster to develop, easily serves multiple applications (service clients), contains fewer risks and requires less development resources. The client object generated from the supplied service interface prototype document is easily integrated into the application to communicate and trigger device-specific service(s).

Real-time solutions

When a remote method of the service interface is called, the engine of AREG SDK immediately generates and delivers messages to the target component, which invokes appropriate methods of addressed service. This makes communication real-time with ultra-low networking latency. Such solutions are highly required to develop time-sensitive applications for automotive, flock of drones, medtech, real-time manufacturing, real-time monitoring and other projects.

Digital twin

Often, the digital twin applications use client-server architecture, where the middleware server collects the data of external devices and the UI application virtualizes them. In such solutions, devices interact either through server or UI client applications. The event-driven and the service-oriented architecture, and the real-time communication of AREG SDK is a perfect solution to develop digital twin applications that virtualize, monitor and control external devices, and immediately react to environment or device state change in real-time mode. External devices may also communicate without additional layers, which is an important factor for emergency, security and safety cases.

Simulation and test automations

When hardware provisioning to all employees is impossible, testing and checking unexpected phenomena of rapidly changing software in a simulated environment can be the most rational solution. If unit tests are used by developers to test a small portion of code and they may contain bugs, the simulation is used by developers and testers to check the system's functionality and stability. Simulations are portable and accessible to everyone, help to optimize solutions and avoid unnecessary risks. Projects using simulations are better prepared for remote work and easier to outsource. The software components in applications normally are split into Data, Controller, Business and the optional Presentation layers. Distributed and service-oriented solution of the AREG engine eases system testing in a simulated environment, where the Simulation application provides an implementation of Data layer services, so that the rest of the application can be tested without any change.

The same technique of simulating data can be used to create API-driven test automations.

[ ↑ to top ↑ ]

---

Examples[](./docs/img/pin.svg)

There are various [examples](./examples/) to demonstrate features of the AREG SDK. The examples are listed in the [examples/README.md](./examples/README.md) document.

[ ↑ to top ↑ ]

---

Licensing[](./docs/img/pin.svg)

AREG SDK is dual-licensed under free open source license (Apache version 2 license) and commercial license, which gives the commercial support, full rights to create and distribute software without open source license obligations. For licensing details see [LICENSE](./LICENSE.txt) document.

For commercial license, support or additional information, please visit Aregtech website or contact info[at]aregtech.com.

[ ↑ to top ↑ ]

---

Call for action[](./docs/img/pin.svg)

We look for help and welcome to join the project:

• See the list of open issues where we look for help.
• If you need new features, please open new issue or start new discussion.
• Please submit your pull requests in the candidate branch, which is our branch with latest sources.
• When create a pull request, please understand that reviewing and testing takes time, and we as well pay attention on coding style.
• If you look for invoiced commercial support or trainings, or if your project has possibility commercially support AREG SDK, please contact info[at]aregtec[dot]com.

Did we help your project or did you just like the idea? Have you learned something new or have we inspired you for new great ideas? Then we ask you not to be indifferent and . This small thank will inspire our contributors and help us expand our community. Please also share the project with your connections on and other social media platforms.

[ ↑ to top ↑ ]

---

Follow us

---

<!-- markdownlint-enable -->