diff --git a/docs/ServiceInterface.md b/docs/ServiceInterface.md index 8268ed86..28d89d5a 100644 --- a/docs/ServiceInterface.md +++ b/docs/ServiceInterface.md @@ -1,68 +1,66 @@ -# Service Interface +Here's the revised document with improved readability, formatting, and wording: + +--- + +# Service Interface ``` -This file is part of AREG SDK -Copyright (c) 2021-2023, Aregtech -Contact: info[at]aregtech.com -Website: https://www.aregtech.com +This file is part of AREG SDK +Copyright (c) 2021-2023, Aregtech +Contact: info[at]aregtech.com +Website: https://www.aregtech.com ``` ## Table of Contents -- [Service Interface](#service-interface) - - [Table of Contents](#table-of-contents) - - [General Information](#general-information) - - [Service Interface Prototype](#service-interface-prototype) - - [Public and Local Services](#public-and-local-services) - - [Data Types](#data-types) - - [Structures](#structures) - - [Enumerations](#enumerations) - - [Imported Types](#imported-types) - - [Containers](#containers) - - [Attributes](#attributes) - - [Requests, Responses, and Broadcasts](#requests-responses-and-broadcasts) - - [Requests](#requests) - - [Responses](#responses) - - [Broadcasts](#broadcasts) - - [Constants](#constants) - - [Includes](#includes) - - [Code Generator](#code-generator) - - [Generated Codes](#generated-codes) +- [General Information](#general-information) +- [Service Interface Prototype](#service-interface-prototype) +- [Public and Local Services](#public-and-local-services) +- [Data Types](#data-types) + - [Structures](#structures) + - [Enumerations](#enumerations) + - [Imported Types](#imported-types) + - [Containers](#containers) +- [Attributes](#attributes) +- [Requests, Responses, and Broadcasts](#requests-responses-and-broadcasts) + - [Requests](#requests) + - [Responses](#responses) + - [Broadcasts](#broadcasts) +- [Constants](#constants) +- [Includes](#includes) +- [Code Generator](#code-generator) +- [Generated Codes](#generated-codes) --- ## General Information -The AREG (*Automated Real-time Event Grid*) is a powerful interface-centric real-time communication engine that facilitates the seamless interaction between connected Things. By acting as ultra-small servers and forming a distributed network of services, AREG simplifies the physical location, discovery, and connection processes for service providers and clients, making communication automatic and transparent. Service providers process requests and provide data, while clients receive responses and have the ability to dynamically subscribe and unsubscribe to data. +The AREG (*Automated Real-time Event Grid*) SDK provides a robust, interface-based real-time communication engine. AREG enables seamless communication between interconnected components, known as Things, which can act as microservers within a distributed network. This simplifies discovering, connecting, and interacting with services, automating the exchange between providers and consumers. Service providers handle requests and deliver data, while clients receive responses and can dynamically subscribe to data updates. -To simplify the definition of the Service Interface and eliminate the need for manual creation of Stub, Client, and Event objects, the AREG SDK provides a Service Interface Prototype XML structured document file and a code generator. This allows developers to quickly and easily define their Service Interface and generate the necessary code artifacts. +To streamline the creation of Service Interfaces and reduce the need for manual coding, the AREG SDK offers a Service Interface Prototype XML document structure, along with a code generator. This setup allows developers to define Service Interfaces efficiently, generating the required code artifacts automatically. -This document serves as a comprehensive developer guide, outlining the structure and format of the Service Interface prototype document. It provides detailed instructions on how to create a Service Interface using the XML document and how to utilize the code generator to automate the code generation process. - -By following the guidelines presented in this document, developers can efficiently define their Service Interfaces and leverage the full capabilities of the AREG Framework, enabling the seamless communication and interaction between services and clients within their applications. +This guide outlines the structure and syntax of the Service Interface Prototype XML document, detailing how to define Service Interfaces and use the code generator effectively within the AREG framework. --- ## Service Interface Prototype -The Service Interface Prototype is an XML document that defines the structure and specifications of a service API. It consists of the following sections: - -1. Service Interface Overview: Provides an overview of the service and its functionality. -2. Service-Specific Data Types: Defines any custom data types used by the service. -3. Service Attributes: Describes the service-specific data or state. -4. Requests, Responses, and Broadcasts: Specifies the service-specific methods for sending requests, receiving responses, and broadcasting events. -5. Constants: Defines any constants specific to the service. -6. Additional Includes: Lists any additional includes required by the service interface. +The Service Interface Prototype is an XML document that specifies a service API's structure. It consists of several sections: -The Service Interface Prototype XML document is used by the code generator to create base objects that can be extended and implemented to incorporate the service's business logic. An example of a service interface prototype can be found in the [Sample.siml](./Sample.siml) file. +1. **Overview**: A high-level overview of the service. +2. **Data Types**: Custom data types used by the service. +3. **Attributes**: Data or state specific to the service. +4. **Requests, Responses, and Broadcasts**: Methods for sending requests, receiving responses, and broadcasting events. +5. **Constants**: Read-only values specific to the service. +6. **Additional Includes**: Additional files required for the service interface. -Please note that the Service Interface design GUI tool is currently in development. +Developers can use this XML document as input to the code generator, creating base objects that can then be extended to incorporate specific business logic. A sample XML document is available in [Sample.siml](./Sample.siml). -> 💡 Stay tuned for updates on the development of the Service Interface design [GUI tool](https://github.com/aregtech/areg-sdk-tools). +--- ### Public and Local Services -Here is an example that defines a _Public_ interface for IPC (Inter-Process Communication): +Below is an example defining a _Public_ interface for Inter-Process Communication (IPC): ```xml @@ -70,284 +68,191 @@ Here is an example that defines a _Public_ interface for IPC (Inter-Process Comm ``` -The `` section contains the service interface's name, version, and the `isRemote` flag, which indicates the accessibility of the interface. When `isRemote="true"`, it means the interface is public and accessible by any component within the network. On the other hand, when `isRemote="false"`, the service is designed for multithreading communication and is not accessible outside of the process. Any attempt to call an API of a Local service is ignored by the system. +- `` specifies the interface's name, version, and `isRemote` status. +- `isRemote="true"` marks the service as public and accessible within the network, while `isRemote="false"` restricts it to local (multithreading) communication only. Calls to a local service API from external processes are ignored. -### Data Types +--- + +## Data Types -Service interfaces can include specific data types to declare variables, service data (attributes), and method parameters. The `` section lists the service-specific data types, which should be streamable. Here are the different types that can be defined: +Service interfaces may define custom data types to specify variables, attributes, and parameters. The `` section organizes service-specific data types. These types should be streamable. -#### Structures +### Structures -The structures are declared using the `` tag with the attribute `Type="Structure"`. Each field refers to a predefined type and must support default values, assignment, comparison, copying, and serialization/deserialization in the [IEIOStream](../framework/areg/base/IEIOStream.hpp) object. +Structures are defined with the `` tag and `Type="Structure"`, listing fields and supporting serialization/deserialization. **Example:** ```xml - - 0 - Some field 1 + Field 1 - - - 0 - Just another field - - - + - More field + Field 2 ``` -#### Enumerations +### Enumerations -The enumerations are declared using the `` tag with the attribute `Type="Enumerate"`. Each field can have a value and is automatically streamable. +Enumerations use `` and list possible values. **Example:** ```xml - - -1 - The invalid value of enum + Invalid enum value - 0 - - - - - ``` -#### Imported Types +### Imported Types -The imported types are declared using the `` tag with the attribute `Type="Imported"`. These types may have a namespace and a relative path to the header file where the type is declared. They should support default values, assignment, comparison, copying, and serialization/deserialization in the [IEIOStream](../framework/areg/base/IEIOStream.hpp) object. +Imported types are predefined types from external headers, marked with `Type="Imported"`. **Example:** ```xml - NEMemory areg/base/NEMemory.hpp ``` -#### Containers +### Containers -The containers, or defined types, are declared using the `` tag with the attribute `Type="DefinedType"`. The `` tag specifies the type of container, the `` specifies the type of values, and in the case of maps, the `` specifies the type of keys. All types should support streaming in the [IEIOStream](../framework/areg/base/IEIOStream.hpp). +Containers are composite types, defined with `Type="DefinedType"`. Types include arrays, linked lists, and hash maps. -**Example 1:** Array of uint32 values +**Example 1: Array of uint32 values** ```xml - - + Array uint32 ``` -**Example 2:** Linked list of strings -```xml - - - LinkedList - String - -``` - -**Example 3:** Hash map with string keys and values of type `SomeStruct` +**Example 2:** Hash map with string keys and values of type `SomeStruct` ```xml - HashMap SomeStruct String ``` -> 💡 Note: The examples provided are for illustration purposes and can be adjusted according to the specific requirements of the service interface. - -### Attributes - -The attributes in services are data elements that can be exchanged with service consumers (clients). Clients have the ability to dynamically subscribe or unsubscribe to receive notifications on data updates. The attributes are listed in the `` section and should be serializable in the [IEIOStream](../framework/areg/base/IEIOStream.hpp) object. - -When a *Service Consumer* subscribes to an attribute, it receives a notification containing the cached value and a validation flag. If the data has not been cached or is invalid, the first notification may indicate an *"Invalid"* state. Shortly after, the server sends a second notification with the actual value and data state. It is important to check the data state to respond correctly. +--- -Here are examples of declaring attributes with different notification behaviors: +## Attributes -*1. Attribute that notifies subscribers only when the value changes:* +Attributes are exchangeable data elements between the service provider and clients. Clients can subscribe to receive notifications when data changes. Attributes are listed in the `` section. +**Example**: Attribute that notifies on every change: ```xml - - An attribute that notifies subscribers only when the value changes. - -``` - -*2. Attribute that notifies subscribers each time the value is set (even if not changed):* - -```xml - - - Another attribute that notifies subscribers every time the value is set (even if not changed). + Attribute that notifies subscribers only when the value changes. ``` -> 💡 Note: The examples provided demonstrate the different notification types for attributes. The specific attribute configuration should align with the requirements of the service interface. +--- -### Requests, Responses, and Broadcasts +## Requests, Responses, and Broadcasts -In Services, there are three types of methods: requests, responses, and broadcasts. These methods are defined in the `` section of the service interface XML document. +Service methods are categorized as requests, responses, or broadcasts. -#### Requests +### Requests -The requests are actions initiated by clients and executed on the *Service Provider* (server) side. They follow a request-reply pattern, where clients send requests and the server replies with a response. Requests can either have no response or be linked to a specific response. When a request has a linked response, the processing of the request is blocked until the server replies. Multiple requests can be linked to the same response. All parameters of a request must be serializable. +Requests are client-initiated actions. They can have a linked response, causing the server to reply after execution. -**Example:** A request with no parameter linked to a response: +**Example**: Request with no parameters: ```xml - - Request and response with no parameters. - - - - + ``` -#### Responses +### Responses -The responses are the *Service Providers's* (server's) replies to requests. Each response is linked to at least one request. When the server calls a response, it triggers a remote callback on the client side. Clients can also manually subscribe and unsubscribe from responses without making a request. It allows clients to receive the result of an action without concerning themselves with which component triggered the action. +Responses are server replies to requests, automatically triggering a callback on the client side. -**Example:** Declaration of responses: +**Example**: Response with parameters: ```xml - - - - - Response, where 2 requests can connect. + ``` -#### Broadcasts +### Broadcasts -The broadcasts are special service methods used to fire events and pass multiple data simultaneously. They do not have linked methods and act as events triggered by the *Service Provider* (server). Clients need to manually subscribe to broadcasts during runtime to receive the data. Broadcast data is only available during the call and is not stored beyond that point. Unlike attributes, which provide cached and actual data, broadcasts only notify clients when the server calls the broadcast. +Broadcasts are server-initiated events with no linked requests. Clients must subscribe manually to receive them. -**Example:** Declaration of a broadcast with parameters: +**Example**: Broadcast with parameters: ```xml - Broadcast with parameters. Can pass multiple parameters at once. - - Parameter name must be different from 'param1' in response. - - - - + + ``` -Note: It is important to ensure unique parameter names in responses and broadcasts. If a parameter name is not unique, it must have the same type in all methods to avoid conflicts. +--- -### Constants +## Constants -The constants in the Service Interface XML document facilitate the sharing of read-only values between service providers and clients. These values can be used for various purposes, such as defining timeouts or other configuration parameters. Constants are listed in the `` section of the document. +Constants define read-only values, shared between providers and consumers. -Example: Declaration of a constant: +**Example**: ```xml 100 - Defines a constant for specifying a timeout period. ``` -In the given example, the constant named "SomeTimeout" is declared with a data type of `uint16` and a value of `100`. It can be referenced by both the service provider and clients to ensure consistent behavior throughout the system. - +--- -### Includes +## Includes -The Service Interface XML document allows for the inclusion of additional files or resources that are required by the service provider and service consumers. These includes are listed in the `` section of the document. +The `` section specifies additional files required by the service. -Example: Declaration of includes: +**Example**: ```xml - - Additional include file for mathematical operations. - + ``` -In the provided example, an include file named "NEMath.hpp" from the `areg/base` directory is declared. This inclusion allows the service provider and service consumers to access the functionality provided by the included file, such as mathematical operations. Including relevant files ensures that the necessary dependencies are met and promotes modularity and code reuse within the system. - --- ## Code Generator -The AREG Software Development Kit (SDK) includes a code generator tool located in the [_tools_](../tools/) folder. This tool aims to simplify the coding process and reduce errors by generating base objects based on the definitions provided in the Service Interface XML document. It is important to note that the generated files should not be modified directly but extended to implement the required override functions. - -Typically, service providers will implement _Request_ methods and make decisions on when to call responses, broadcasts, or update attribute data. On the other hand, service clients will implement the relevant _Response_, _Broadcast_, and _Attribute_ update notification methods as needed, making decisions on when to send requests and subscribe to events. - -To generate the source code, you can edit and run the "generate.sh" or "generate.bat" file, or run "codegen.jar" from the command line. Make sure to set the correct `AREG_SDK_ROOT` folder path before running the code generation scripts. +The AREG SDK includes a code generator tool in the [_tools_](../tools/) directory to automate code creation based on the Service Interface XML document. Generated files should not be modified directly; instead, extend the classes and override only necessary functions. -> 💡 To optimize performance and avoid unnecessary code, service consumers should only override the responses, broadcasts, and update notifications that they actually use. Unneeded overrides will never be called. For example, if a service has attributes named `One` and `Two`, and a client is only subscribed to updates for `One`, there is no need to override the update of `Two` since it will never be received. +To generate source code, execute `codegen.jar` with the following parameters: +- `--root`: Project root path. +- `--doc`: Relative path to the Service Interface XML. +- `--target`: Output folder for generated files. -The code generator requires [Java](https://www.java.com/) to be installed on your machine. It requires the following parameters: -- `--root`: Path to the development project. All paths are relative to the root. -- `--doc`: Relative path to the Service Interface XML document for code generation. -- `--target`: Relative path to the output folder for the generated files. - -**Example:** Run the code generator from the command line +**Example**: ```bash java -jar ~/projects/areg-sdk/codegen.jar --root=~/projects/my_project --target=src/generated/ --doc=interface/MyService.siml ``` -Here's an example of a [generate.bat](../examples/12_pubsvc/res/generate.bat) file in the AREG SDK: -```batch -:: Set the AREG_SDK_ROOT directory here -set AREG_SDK_ROOT=C:\Projects\aregtech\areg-sdk -:: .bat file directory -set BATCH_ROOT=%~dp0 -:: In case of examples, one level up. -set PROJECT_ROOT=%BATCH_ROOT%\.. -:: Specify the relative path of the output folder -set CODE_GEN=generated\src -:: Include codegen.jar in the CLASSPATH -set CLASSPATH=%CLASSPATH%;%AREG_SDK_ROOT%\tools;%AREG_SDK_ROOT%\tools\codegen.jar - -@echo Generating class of HelloService Service Interface in folder %CODE_GEN% ..... -java com.aregtech.CMFMain --root=%PROJECT_ROOT% --doc=services\HelloService.siml --target=%CODE_GEN% -``` - -These examples demonstrate how to run the code generator tool from the command line by specifying the necessary parameters. +For more details see [AREG SDK Code Generator (`codegen.jar`)](./wiki/code-generator.md) document. --- ## Generated Codes -The code generator provided by the AREG Software Development Kit (SDK) simplifies the development process by automatically creating source code for both **Service Providers** (*servers*) and **Service Consumers** (*clients*). Additionally, it generates a namespace with the prefix `NE` for shared common data. When creating a server, developers extend classes that end with `Stub`, while clients extend classes that end with `ClientBase`. It is important to note that the files generated in the `private` subdirectory are for internal use only and should not be modified or used directly. - -Here's an example of the folder structure for the generated codes: - -[![File structure after generating codes](https://raw.githubusercontent.com/aregtech/areg-sdk/master/docs/img/generated-sources.png)](https://github.com/aregtech/areg-sdk/blob/master/docs/img/generated-sources.png) - -> 💡 It is recommended to include the generated codes in a separate **static library** that can be linked with both Service Provider and Service Consumer applications. This approach is particularly effective in multiprocessing applications, where Service Providers and Service Consumers run in separate processes or on separate machines. - ---- +The code generator simplifies development by creating classes for **Service Providers** (servers) and **Service Consumers** (clients). It also generates a namespace prefixed with `NE`. Extend classes with `Stub` for servers and `ClientBase` for clients, as required. \ No newline at end of file diff --git a/docs/wiki/cmake-functions.md b/docs/wiki/cmake-functions.md index 77dd6908..438557a8 100644 --- a/docs/wiki/cmake-functions.md +++ b/docs/wiki/cmake-functions.md @@ -4,38 +4,36 @@ The [functions.cmake](./../../conf/cmake/functions.cmake) file in AREG SDK conta ## Table of Contents -- [AREG SDK CMake Functions and Macros](#areg-sdk-cmake-functions-and-macros) - - [Table of Contents](#table-of-contents) - - [Introduction](#introduction) - - [CMake Macro Overview](#cmake-macro-overview) - - [`macro_check_fix_areg_cxx_standard`](#macro_check_fix_areg_cxx_standard) - - [`macro_normalize_path`](#macro_normalize_path) - - [`macro_add_service_interface`](#macro_add_service_interface) - - [`macro_find_package`](#macro_find_package) - - [`macro_create_option`](#macro_create_option) - - [`macro_add_source`](#macro_add_source) - - [`macro_parse_arguments`](#macro_parse_arguments) - - [`macro_declare_static_library`](#macro_declare_static_library) - - [`macro_declare_shared_library`](#macro_declare_shared_library) - - [`macro_declare_executable`](#macro_declare_executable) - - [`macro_setup_compilers_data`](#macro_setup_compilers_data) - - [`macro_setup_compilers_data_by_family`](#macro_setup_compilers_data_by_family) - - [CMake Functions Overview](#cmake-functions-overview) - - [`setAppOptions`](#setappoptions) - - [`addExecutableEx`](#addexecutableex) - - [`addExecutable`](#addexecutable) - - [`setStaticLibOptions`](#setstaticliboptions) - - [`addStaticLibEx`](#addstaticlibex) - - [`addStaticLib`](#addstaticlib) - - [`addStaticLibEx_C`](#addstaticlibex_c) - - [`addStaticLib_C`](#addstaticlib_c) - - [`setSharedLibOptions`](#setsharedliboptions) - - [`addSharedLibEx`](#addsharedlibex) - - [`addSharedLib`](#addsharedlib) - - [`addServiceInterfaceEx`](#addserviceinterfaceex) - - [`addServiceInterface`](#addserviceinterface) - - [`removeEmptyDirs`](#removeemptydirs) - - [`printAregConfigStatus`](#printaregconfigstatus) +- [Introduction](#introduction) +- [CMake Macro Overview](#cmake-macro-overview) + - [`macro_check_fix_areg_cxx_standard`](#macro_check_fix_areg_cxx_standard) + - [`macro_normalize_path`](#macro_normalize_path) + - [`macro_add_service_interface`](#macro_add_service_interface) + - [`macro_find_package`](#macro_find_package) + - [`macro_create_option`](#macro_create_option) + - [`macro_add_source`](#macro_add_source) + - [`macro_parse_arguments`](#macro_parse_arguments) + - [`macro_declare_static_library`](#macro_declare_static_library) + - [`macro_declare_shared_library`](#macro_declare_shared_library) + - [`macro_declare_executable`](#macro_declare_executable) + - [`macro_setup_compilers_data`](#macro_setup_compilers_data) + - [`macro_setup_compilers_data_by_family`](#macro_setup_compilers_data_by_family) +- [CMake Functions Overview](#cmake-functions-overview) + - [`setAppOptions`](#setappoptions) + - [`addExecutableEx`](#addexecutableex) + - [`addExecutable`](#addexecutable) + - [`setStaticLibOptions`](#setstaticliboptions) + - [`addStaticLibEx`](#addstaticlibex) + - [`addStaticLib`](#addstaticlib) + - [`addStaticLibEx_C`](#addstaticlibex_c) + - [`addStaticLib_C`](#addstaticlib_c) + - [`setSharedLibOptions`](#setsharedliboptions) + - [`addSharedLibEx`](#addsharedlibex) + - [`addSharedLib`](#addsharedlib) + - [`addServiceInterfaceEx`](#addserviceinterfaceex) + - [`addServiceInterface`](#addserviceinterface) + - [`removeEmptyDirs`](#removeemptydirs) + - [`printAregConfigStatus`](#printaregconfigstatus) --- diff --git a/examples/10_locsvc/ReadMe.md b/examples/10_locsvc/ReadMe.md index 9b8396a6..a1d9a085 100644 --- a/examples/10_locsvc/ReadMe.md +++ b/examples/10_locsvc/ReadMe.md @@ -1,6 +1,6 @@ # 10_locsvc Project Overview -The **10_locsvc** project demonstrates creating and managing a **Local Service** within the AREG Framework, using the Service Interface document and AREG SDK�s code generator. This example shows how to build a service provider and consumer that communicate asynchronously within a single, multithreaded process, without external visibility. +The **10_locsvc** project demonstrates creating and managing a **Local Service** within the AREG Framework, using the Service Interface document and AREG SDK’s code generator. This example shows how to build a service provider and consumer that communicate asynchronously within a single, multithreaded process, without external visibility. The **Local Service** interface is defined in the [HelloWorld.siml](./services/HelloWorld.siml) file, and the corresponding source code is automatically generated during the build process via `codegen.jar`. diff --git a/examples/12_pubsvc/12_generated.vcxproj.filters b/examples/12_pubsvc/12_generated.vcxproj.filters index 0334989d..34559115 100644 --- a/examples/12_pubsvc/12_generated.vcxproj.filters +++ b/examples/12_pubsvc/12_generated.vcxproj.filters @@ -14,9 +14,6 @@ bat;rc;ico;cur;bmp;dlg;rc2;rct;bin;rgs;gif;jpg;jpeg;jpe;resx;tiff;tif;png;wav;mfcribbon-ms - - - Source Files @@ -51,4 +48,9 @@ Header Files + + + Resource Files + + \ No newline at end of file diff --git a/examples/12_pubsvc/ReadMe.md b/examples/12_pubsvc/ReadMe.md index 4cb97daa..f4f0dd58 100644 --- a/examples/12_pubsvc/ReadMe.md +++ b/examples/12_pubsvc/ReadMe.md @@ -20,7 +20,7 @@ The **12_pubsvc** project demonstrates the implementation of a *Public Service* - An application acting as a network-discoverable *Public Service* provider. It listens for remote requests from consumers and processes them. Multiple *Service Consumers* can connect to the provider simultaneously, sending requests to be handled. 3. **[12_pubclient](./pubclient/)**: - - An application that acts as a *Public Service* consumer. The client application automatically discovers the *Public Service* provider using AREG Frameworks�s built-in service discovery. It periodically sends remote request calls using a timer, simulating real-world use cases where a service might need regular interactions with the provider. + - An application that acts as a *Public Service* consumer. The client application automatically discovers the *Public Service* provider using AREG Frameworks’s built-in service discovery. It periodically sends remote request calls using a timer, simulating real-world use cases where a service might need regular interactions with the provider. ## Communication @@ -31,7 +31,7 @@ The **12_pubsvc** project demonstrates the implementation of a *Public Service* - **Automatic Service Discovery**: AREG Framework automates the discovery of the *Public Service*, so *Service Consumers* can easily connect to the provider without needing explicit configuration. This ensures smooth communication even when the processes are started in any order. -- **Fault Tolerance**: The AREG SDK ensures fault tolerance in service communication, meaning if a service fails, it can recover or restart without affecting the overall system�s operation. +- **Fault Tolerance**: The AREG SDK ensures fault tolerance in service communication, meaning if a service fails, it can recover or restart without affecting the overall system’s operation. - **Efficient Communication**: By using **Object RPC** for communication, the system reduces overhead and simplifies the development process. It ensures that requests and responses between the provider and consumers are dispatched efficiently. diff --git a/examples/13_pubmesh/ReadMe.md b/examples/13_pubmesh/ReadMe.md index b7a67f47..140ba3f0 100644 --- a/examples/13_pubmesh/ReadMe.md +++ b/examples/13_pubmesh/ReadMe.md @@ -1,6 +1,6 @@ # 13_pubmesh Project Overview -The **13_pubmesh** project demonstrates the AREG Framework�s capability to manage a **meshed network** of **distributed services**, integrating both **Public** and **Local Services**. The project showcases how the framework efficiently connects **Service Providers** and **Service Consumers** to handle **inter-process communication (IPC)** using *Object Remote Procedure Call (Object RPC)*, enabling scalable and reliable communication across the network. +The **13_pubmesh** project demonstrates the AREG Framework’s capability to manage a **meshed network** of **distributed services**, integrating both **Public** and **Local Services**. The project showcases how the framework efficiently connects **Service Providers** and **Service Consumers** to handle **inter-process communication (IPC)** using *Object Remote Procedure Call (Object RPC)*, enabling scalable and reliable communication across the network. > [!IMPORTANT] > To test this example, ensure an `mcrouter` process is running on a network-accessible machine to enable message routing. Verify that the `areg.init` configuration file includes the correct IP address and port number for the `mcrouter`. diff --git a/examples/14_pubtraffic/ReadMe.md b/examples/14_pubtraffic/ReadMe.md index ea178f29..8db421cf 100644 --- a/examples/14_pubtraffic/ReadMe.md +++ b/examples/14_pubtraffic/ReadMe.md @@ -24,7 +24,7 @@ The **14_pubtraffic** project demonstrates how to dynamically create and manage ## Communication -Communication between the service provider and consumers is facilitated by **mcrouter** router, which is capable of operating across any networked machine. The AREG Framework automates **service discovery** and ensures **fault tolerance**, enabling reliable **IPC** and ensuring that the order of process startup does not affect the system�s functionality. Services are automatically discovered, and messages are forwarded seamlessly to their intended recipients, maintaining robust inter-process communication. +Communication between the service provider and consumers is facilitated by **mcrouter** router, which is capable of operating across any networked machine. The AREG Framework automates **service discovery** and ensures **fault tolerance**, enabling reliable **IPC** and ensuring that the order of process startup does not affect the system’s functionality. Services are automatically discovered, and messages are forwarded seamlessly to their intended recipients, maintaining robust inter-process communication. ## Key Features @@ -36,8 +36,8 @@ Communication between the service provider and consumers is facilitated by **mcr - **Dynamic Runtime Model Creation**: This project is ideal for applications that require models or objects to be created dynamically during runtime, offering flexibility in service configuration and operation. - **Real-time Inter-Process Communication (IPC)**: Suitable for systems where real-time communication between distributed services is essential, leveraging **Object RPC** and **IPC** to ensure reliable message exchange. -- **Custom Event-Driven Systems**: Applications that rely on custom event handling can benefit from the project�s approach to managing user-triggered events in a multithreaded environment. +- **Custom Event-Driven Systems**: Applications that rely on custom event handling can benefit from the project’s approach to managing user-triggered events in a multithreaded environment. ## Conclusion -The **14_pubtraffic** project highlights the AREG SDK�s capabilities in managing **dynamic models** and **custom events** within a **multithreaded** and **distributed system**. Through the use of **Object RPC** and **IPC**, the project demonstrates how to achieve real-time communication and event handling, making it a valuable example for developers looking to build scalable, event-driven applications. +The **14_pubtraffic** project highlights the AREG SDK’s capabilities in managing **dynamic models** and **custom events** within a **multithreaded** and **distributed system**. Through the use of **Object RPC** and **IPC**, the project demonstrates how to achieve real-time communication and event handling, making it a valuable example for developers looking to build scalable, event-driven applications. diff --git a/examples/15_pubworker/ReadMe.md b/examples/15_pubworker/ReadMe.md index bbe9140b..25d4b5ff 100644 --- a/examples/15_pubworker/ReadMe.md +++ b/examples/15_pubworker/ReadMe.md @@ -20,7 +20,7 @@ The **15_pubworker** project demonstrates the use of **Worker Threads** to perfo - This sub-project includes a **Service Consumer** and a **Worker Thread**. The Worker Thread simulates an output device, performing tasks in the background while the service consumer interacts with the public service provider. 3. **[15_pubservice](./pubservice/)**: - - This sub-project hosts a **Public Service Provider** along with a **Worker Thread** that processes user inputs from the console and updates the service�s attributes. Both the service and worker thread are part of the static model, which is initialized at startup and unloaded at exit. + - This sub-project hosts a **Public Service Provider** along with a **Worker Thread** that processes user inputs from the console and updates the service’s attributes. Both the service and worker thread are part of the static model, which is initialized at startup and unloaded at exit. ## Communication diff --git a/examples/16_pubfsm/ReadMe.md b/examples/16_pubfsm/ReadMe.md index ec799d49..03824bc4 100644 --- a/examples/16_pubfsm/ReadMe.md +++ b/examples/16_pubfsm/ReadMe.md @@ -1,6 +1,6 @@ # 16_pubfsm Project Overview -The **16_pubfsm** project demonstrates how to build and manage a *Finite-State Machine* (**FSM**) using the AREG Framework�s powerful features like *Timers* and *Events*. This project showcases how FSM models can be developed to change the data and the states of Services. +The **16_pubfsm** project demonstrates how to build and manage a *Finite-State Machine* (**FSM**) using the AREG Framework’s powerful features like *Timers* and *Events*. This project showcases how FSM models can be developed to change the data and the states of Services. > [!IMPORTANT] > To test this example, ensure an `mcrouter` process is running on a network-accessible machine to enable message routing. Verify that the `areg.init` configuration file includes the correct IP address and port number for the `mcrouter`. @@ -33,7 +33,7 @@ The **16_pubfsm** project demonstrates how to build and manage a *Finite-State M ## Communication and Service Discovery -- **mcrouter**: The communication between the *Service Provider* and *Service Consumers* is managed through `mcrouter`, AREG�s router for handling RPC message routing and inter-process communication. +- **mcrouter**: The communication between the *Service Provider* and *Service Consumers* is managed through `mcrouter`, AREG’s router for handling RPC message routing and inter-process communication. - **Service Discovery and Fault Tolerance**: The AREG Framework ensures automatic service discovery and fault tolerance, meaning the order in which services start is irrelevant. This makes the system robust and reliable even in unpredictable environments. ## Use Cases @@ -44,4 +44,4 @@ The **16_pubfsm** project demonstrates how to build and manage a *Finite-State M ## Conclusion -The **16_pubfsm** project highlights the AREG Framework�s ability to efficiently implement a *Finite-State Machine*. Whether you're developing device application or any event-driven systems, this project provides a scalable, robust solution using FSM, triggers, timers, and events. By leveraging the AREG SDK�s features like service discovery and fault tolerance, developers can focus on building highly reliable, state-based systems with ease. +The **16_pubfsm** project highlights the AREG Framework’s ability to efficiently implement a *Finite-State Machine*. Whether you're developing device application or any event-driven systems, this project provides a scalable, robust solution using FSM, triggers, timers, and events. By leveraging the AREG SDK�s features like service discovery and fault tolerance, developers can focus on building highly reliable, state-based systems with ease. diff --git a/examples/19_pubwatchdog/ReadMe.md b/examples/19_pubwatchdog/ReadMe.md index 3fbe87ca..5b858419 100644 --- a/examples/19_pubwatchdog/ReadMe.md +++ b/examples/19_pubwatchdog/ReadMe.md @@ -29,7 +29,7 @@ The **19_pubwatchdog** project demonstrates the use of a **Watchdog** in an envi ## Communication -Communication between the service provider and consumers is facilitated by **mcrouter** router, which is capable of operating across any networked machine. The AREG Framework automates **service discovery** and ensures **fault tolerance**, enabling reliable **IPC** and ensuring that the order of process startup does not affect the system�s functionality. Services are automatically discovered, and messages are forwarded seamlessly to their intended recipients, maintaining robust inter-process communication. +Communication between the service provider and consumers is facilitated by **mcrouter** router, which is capable of operating across any networked machine. The AREG Framework automates **service discovery** and ensures **fault tolerance**, enabling reliable **IPC** and ensuring that the order of process startup does not affect the system’s functionality. Services are automatically discovered, and messages are forwarded seamlessly to their intended recipients, maintaining robust inter-process communication. ## Key Features diff --git a/examples/21_pubunblock/ReadMe.md b/examples/21_pubunblock/ReadMe.md index f9e5247a..3535056b 100644 --- a/examples/21_pubunblock/ReadMe.md +++ b/examples/21_pubunblock/ReadMe.md @@ -24,13 +24,13 @@ The **21_pubunblock** project demonstrates how to handle and manually unblock se ## Communication -Communication between the service provider and consumers is facilitated by **mcrouter** router, which is capable of operating across any networked machine. The AREG Framework automates **service discovery** and ensures **fault tolerance**, enabling reliable **IPC** and ensuring that the order of process startup does not affect the system�s functionality. Services are automatically discovered, and messages are forwarded seamlessly to their intended recipients, maintaining robust inter-process communication. +Communication between the service provider and consumers is facilitated by **mcrouter** router, which is capable of operating across any networked machine. The AREG Framework automates **service discovery** and ensures **fault tolerance**, enabling reliable **IPC** and ensuring that the order of process startup does not affect the system’s functionality. Services are automatically discovered, and messages are forwarded seamlessly to their intended recipients, maintaining robust inter-process communication. ## Key Features - **Request Manual Unblocking**: The core feature of this project is the ability to manually unblock requests, allowing the service provider to continue processing new requests while waiting to complete ongoing ones. This prevents the system with asynchronous communication from stalling. - **Non-Blocking Client Responses**: Normally, when a client request is processed and the developer replies with the response, the system automatically prepares the response and sends to the target Consumer. In case of manual request unblocking, the develop needs manually preparing response, then reply with the response. This response preparation mechanism ensures that the right target Consumer receives the response. -- **Fault-Tolerant Communication**: Leveraging `mcrouter` and the AREG SDK�s fault-tolerant capabilities, the system can manage communication failures gracefully, ensuring that service providers and consumers can reconnect and resume operations without data loss. +- **Fault-Tolerant Communication**: Leveraging `mcrouter` and the AREG SDK’s fault-tolerant capabilities, the system can manage communication failures gracefully, ensuring that service providers and consumers can reconnect and resume operations without data loss. ## Use Cases diff --git a/examples/22_pubsub/ReadMe.md b/examples/22_pubsub/ReadMe.md index d0bea0e4..e6e64458 100644 --- a/examples/22_pubsub/ReadMe.md +++ b/examples/22_pubsub/ReadMe.md @@ -31,7 +31,7 @@ This project uses **Object Remote Procedure Call (Object RPC)** for efficient ** ## Communication -Communication between the service provider and consumers is facilitated by **mcrouter** router, which is capable of operating across any networked machine. The AREG Framework automates **service discovery** and ensures **fault tolerance**, enabling reliable **IPC** and ensuring that the order of process startup does not affect the system�s functionality. Services are automatically discovered, and messages are forwarded seamlessly to their intended recipients, maintaining robust inter-process communication. +Communication between the service provider and consumers is facilitated by **mcrouter** router, which is capable of operating across any networked machine. The AREG Framework automates **service discovery** and ensures **fault tolerance**, enabling reliable **IPC** and ensuring that the order of process startup does not affect the system’s functionality. Services are automatically discovered, and messages are forwarded seamlessly to their intended recipients, maintaining robust inter-process communication. ## Key Features @@ -50,4 +50,4 @@ Communication between the service provider and consumers is facilitated by **mcr ## Conclusion -The **22_pubsub** project showcases a scalable implementation of the Pub/Sub model, supporting effective communication between distributed processes with **Object RPC** and **IPC**. By leveraging the AREG SDK�s service discovery and fault tolerance, the project provides a reliable and flexible solution for real-time data distribution in multi-process environments. This project is suited for scenarios requiring efficient, continuous data streams, demonstrating how publishers and subscribers interact smoothly in a distributed system. +The **22_pubsub** project showcases a scalable implementation of the Pub/Sub model, supporting effective communication between distributed processes with **Object RPC** and **IPC**. By leveraging the AREG SDK’s service discovery and fault tolerance, the project provides a reliable and flexible solution for real-time data distribution in multi-process environments. This project is suited for scenarios requiring efficient, continuous data streams, demonstrating how publishers and subscribers interact smoothly in a distributed system. diff --git a/examples/23_pubsubmix/ReadMe.md b/examples/23_pubsubmix/ReadMe.md index 3230ef83..1123fd0a 100644 --- a/examples/23_pubsubmix/ReadMe.md +++ b/examples/23_pubsubmix/ReadMe.md @@ -36,7 +36,7 @@ Using **Object Remote Procedure Call (Object RPC)** for efficient **Inter-Proces - **Hybrid Communication**: The Pub/Sub system supports both local and remote subscribers, allowing any process to function as both a **Publisher** and **Subscriber** simultaneously. - **Network Resilience**: All **Publishers** and **Subscribers** within the same process receive updates regardless of network connectivity, ensuring uninterrupted service. -- **Immediate Data Updates**: Subscribers automatically receive the latest data upon connecting, ensuring they�re always up-to-date even if no recent updates have been published. +- **Immediate Data Updates**: Subscribers automatically receive the latest data upon connecting, ensuring they’re always up-to-date even if no recent updates have been published. - **Dynamic Subscription and Publishing**: Both *23_pubsubctrl* and *23_pubsubdyn* can seamlessly switch between publisher and subscriber roles, making the system highly adaptable in dynamic, multi-process environments. - **Fault-Tolerant Communication**: With `mcrouter` and the AREG SDK, the system remains fault-tolerant, supporting automatic service discovery and recovery, ensuring reliable Pub/Sub functionality even during failures. diff --git a/examples/24_pubsubmulti/ReadMe.md b/examples/24_pubsubmulti/ReadMe.md index c986d73e..880f532e 100644 --- a/examples/24_pubsubmulti/ReadMe.md +++ b/examples/24_pubsubmulti/ReadMe.md @@ -7,7 +7,7 @@ The **24_pubsubmulti** project demonstrates the use of a *Public Service* in a m ## Key Concepts -- **Efficient Event Delivery**: The project illustrates how AREG�s Pub/Sub system minimizes event notifications by sending updates only when necessary, ensuring that subscribers receive only relevant data. +- **Efficient Event Delivery**: The project illustrates how AREG’s Pub/Sub system minimizes event notifications by sending updates only when necessary, ensuring that subscribers receive only relevant data. - **Multiple Subscribers in One Thread**: It demonstrates a scenario where multiple subscribers, residing in the same thread, subscribe to the same data, but at different times. - **Dynamic Subscription**: Each subscriber can dynamically subscribe to the published data, with notifications sent only when the data changes or based on predefined settings. @@ -38,7 +38,7 @@ This dual-mode notification system offers flexibility depending on the use case, ## Key Features -- **Optimized Data Delivery**: AREG Frameworks�s Pub/Sub system ensures that updates are sent efficiently, reducing unnecessary message traffic. This results in more optimized performance, especially in systems with multiple subscribers. +- **Optimized Data Delivery**: AREG Frameworks’s Pub/Sub system ensures that updates are sent efficiently, reducing unnecessary message traffic. This results in more optimized performance, especially in systems with multiple subscribers. - **Multiple Subscribers in One Thread**: The ability to have multiple subscribers within the same thread receiving data updates demonstrates how AREG Framework can handle complex subscription scenarios without performance overhead. - **Automatic Service Discovery**: The AREG Framework automates the discovery of the publisher by the subscribers, making process startup order irrelevant. Subscribers can dynamically connect to the publisher without needing to know the details of its location beforehand. @@ -46,8 +46,8 @@ This dual-mode notification system offers flexibility depending on the use case, - **Real-Time Data Monitoring**: The **24_pubsubmulti** project is ideal for applications where real-time data updates need to be delivered to multiple subscribers efficiently. This is particularly useful in scenarios where minimizing network traffic is important. - **Multiple Subscriber Scenarios**: The ability to run multiple subscribers in a single process or a thread demonstrates how complex subscription patterns can be managed without introducing additional resource consumption. -- **Change-Driven Notifications**: The project�s support for *On Change* notifications makes it suitable for applications where updates are required only when data values change, improving performance in bandwidth-constrained environments. +- **Change-Driven Notifications**: The project’s support for *On Change* notifications makes it suitable for applications where updates are required only when data values change, improving performance in bandwidth-constrained environments. ## Conclusion -The **24_pubsubmulti** project showcases an efficient Pub/Sub system for multi-process environments, with a focus on minimizing event generation and ensuring efficient data delivery. By allowing multiple subscribers to coexist within a single thread and dynamically receive updates, the project highlights how AREG Framework�s Pub/Sub features can be used to build scalable and high-performance systems. The use of **Object RPC** for **Inter-Process Communication (IPC)**, combined with the fault-tolerant communication of `mcrouter`, ensures that the system remains robust and flexible, making it suitable for a wide range of real-time data distribution use cases. +The **24_pubsubmulti** project showcases an efficient Pub/Sub system for multi-process environments, with a focus on minimizing event generation and ensuring efficient data delivery. By allowing multiple subscribers to coexist within a single thread and dynamically receive updates, the project highlights how AREG Framework’s Pub/Sub features can be used to build scalable and high-performance systems. The use of **Object RPC** for **Inter-Process Communication (IPC)**, combined with the fault-tolerant communication of `mcrouter`, ensures that the system remains robust and flexible, making it suitable for a wide range of real-time data distribution use cases.