Build and configure your own client/worker test

You can also develop your own client to submit jobs to ArmoniK and invoke desired services, which are embedded in the worker-shared library.

Client test

The SessionService class in ArmoniK::Sdk::Client namespace is used to create a client. This class essentially contains methods for sending tasks to ArmoniK and retrieving the results. These methods are Submit and WaitResults respectively.

Configure client

The constructor of the SessionService class takes as arguments a properties and a logger objects. The properties object as defined in ArmoniK::Sdk::Common namespace contain the configuration and a session task options objects.

  • The configuration object is loaded from a JSON file or from environment variables that define the following:
    • Endpoint: The control plane address to which clients connect.
    • mTLS: enable or disable mTLS.
    • caCert: The Server certificate file to validate mTLS.
    • clientCert: The client certificate fil in a pem format.
    • clientKey: The client key file in a pem format.
    • sslValidation: Disable the ssl strong validation of ssl certificate (default: enable => true). The environment variables override the configuration in the JSON files.
  • The session task options contain information required by a session such as the following:
    • MaxRetries (default value is set to 2)
    • Priority (default value is set to 1)
    • AppName the name of the worker shared library
    • AppVersion the version of the library (can be empty)
    • AppNamespace the service namespace
    • AppService the service name

Setup your own client

To set up a SessionService, these values mentioned above must be specified to set properties, and the logger in ArmoniK API must be used.

The Submit method can be used to send tasks to ArmoniK worker asynchronously. The method returns a list of submitted task IDs. This method requires two arguments: the task payload and the invocation handler.

  • The task payload is a vector containing a list of task requests. The task payload includes information such as:
    • The name of the method to be invoked.
    • The serialized arguments for the invoked method.
    • The data dependencies (empty by default).
  • The invocation handler to return a handle response or error.

Before submitting tasks to ArmoniK, we must first provide the implementation of an abstract class IServiceInvocationHandler for the invocation handler. This class contains two pure virtual methods which are HandleResponse and HandleError that must be implemented.

  • The HandleResponse is the callback function to manage the result in case of success. The arguments of this function are serialized data coming from the server as a result of the method invoked by the client and the task id that invoked the callback.
  • The HandleError is the callback function to retrieve errors or exceptions. The arguments are the exception sent to the control plane and the task id that caused the error.

The WaitResultsretrieves results of submitted tasks. This method waits for a given set of tasks to retrieve results. If no tasks are specified, then the method waits for all the tasks launched with this service to be completed. If a set of tasks is specified then the waitBehavior parameter defines when the function returns. This method takes as arguments a set of task IDs, a waitBehavior, and a waitOptions.

  • Task ids is an array set with the ids of tasks for which we are waiting for the results. If other tasks have been launched with the service, they may be handled at the same time as the tasks in the set. If empty, the function will wait on the results of all the tasks submitted with this service.
  • WaitBahavior specifies if it should wait for all tasks, any task completion, and/or stop waiting if a result is aborted from the given task_ids list. If the task_ids set is empty, All and Any are synonymous. If the waitBehavior contains the BreakOnError flag, the function exits after a result sent by this service is aborted.
  • WaitOptions specifies the amount of time between result status checks.

Worker

The ArmoniK dynamic worker deployed with the infrastructure is responsible for receiving tasks from clients and executing them based on the task options and the task payloads. The methods to be invoked are determined in the task payload with their serialized arguments. The implementation of those methods must be present in the worker-shared library as a ServiceBase object. In the following, we show how to set up and build this shared library.

Worker service implementation

To create an ArmoniK Worker Service, a shared library exposing 5 mandatory symbols must be created (cf ArmoniK SDK Interface). This library must then be deployed either by copying it to the shared folder ARMONIK_SHARED_HOST_PATH, or by copying it in the Docker container run by the compute plane. The latter option may require overriding the default application search path by giving the environment variable Worker__ApplicationBasePath to the directory where the library is located.

The application_name and application_version task options are then determined by the name of the library such that “application_name.application_version” or “application_name” is the name of the library file. This library will be loaded and unloaded according to the task options of the task being processed by the worker. The different calls to the symbols and the expected lifetimes of the service and sessions within a worker pod are described in the flowchart presented in the appendix section.

Setup worker shared lib

It is possible to set up a shared library in order to extend the ArmoniK Worker. In order to facilitate writing this shared library it is recommended to link your own code to the ArmoniK.SDK.Worker static library. It provides default implementation of mandatory symbols (armonik_enter_session, armonik_enter_session, armonik_call, armonik_leave_session and armonik_destroy_service) . These symbols will be explained later in this section. Please note that ArmoniK.SDK.Worker static library is to be used with C++ workers (C++14 or later).

To do so, an implementation of a service class inheriting of ArmoniK::Sdk::Worker::ServiceBase must be provided. The developer could override previously cited symbols or keep their default implementations as they are. However armonik_create_service symbol is not provided by ServiceBase and must be implemented by the user. An example of this kind of implementation can be found in Echo service or Addition service. The examples provide the service class implementing the methods called when entering, calling or leaving a session using the ArmoniK::Sdk::Worker. When using this approach, users may only provide the implementation of the creation of armonik_create_service as in here.

Another way to set up the shared library without inheriting ArmoniK::Sdk::Worker::ServiceBase consists in providing an implementation of the following mandatory methods: armonik_create_service This symbol is mandatory and allows to create a service based on its name and namespace. This function should be implemented by the library and return a service context. This service context will be passed to the subsequent calls to other symbols. The returned context may be null if desired. armonik_enter_session This symbol will be called when entering a session. This function returns a user defined session context. armonik_call This symbol will be called to request the execution of a method. This function returns the status of the ArmoniK call. The function takes multiple arguments including a Callback provided by ArmoniK to send the result of the execution or details on a failure. See the symbols documentation for more details here. armonik_leave_session This function is called when leaving a session. It should free the resources of the session context. armonik_destroy_service This function is called when the service should be destroyed. It should free the resources of the service context.

Edit this page on GitHub
Table of Contents