Technical details of Kanzi Connect services

You can run Kanzi Connect services either locally in Kanzi Connect Server or remotely outside the server process. See Local services and Remote services

Local services

The diagram below is a slightly simplified initialization and execution graph for a service that is run in Kanzi Connect Server. It shows the execution contexts related to service creation and runtime operation, leaving out unnecessary details.

Most of the operations are to be run in the main thread context (marked in blue). Especially the initialization and registration should be done in the same thread that later periodically calls the Server::processMessage message handler. Calls to Server::processMessage block the execution until there is something to process. You can interrupt it:

  • With a message received from the network

  • With a service with background worker threads invoking the AbstractService::notifyWork() method

  • By calling Server::quit from some other thread

../_images/local-service-execution-diagram.png

Take these things into account when implementing local services:

  • Access the Kanzi Connect API, including property updates, only from the main thread context.

    For example, if you need a periodic operation, create a dedicated thread that periodically invokes the notifyWork method of AbstractService.

  • If you need parallelization in the method handling of the service, execute long-lasting operations in worker threads.

Remote services

The same services that are run as attached to Kanzi Connect Server you can also run remotely so that they connect to Kanzi Connect equally as clients to implement service functionality outside the server.

To run services remotely you need a service runner. Kanzi Connect comes with a remoteservicerunner you can customize. See Running services remotely.

The diagram below shows the execution contexts in which different operations related to remote services are run. Remote services are always executed in two main contexts:

  • The network thread (marked in green) handles the communication with the physical network bearer (TCP, SSL, …). It operates in the background and is not directly visible to Kanzi Connect API users.

  • The main thread (marked in blue) handles most of the relevant operations, including all the initializations and runtime operations, such as handling of method calls issued by networked clients. Kanzi Connect developers operate in this context.

For example, when an external client invokes a remote service method, the network thread first receives the message package. It signals about the received message which causes the ClientRemoteServiceHost to retrieve the pending message. This occurs in the main thread context. The message is decoded and the corresponding service method (in the diagram below longLastingMethodCall) is invoked.

You can also create various worker threads (marked in yellow) to cover different scenarios. To avoid blocking the main thread, long-lasting method calls can launch a worker thread. Such a method should at its completion issue the AbstractService method notifyWork. This transfers the context to the main thread and invokes the work method of the service. The Kanzi Connect C++ API allows you to use the notifyWork method to provide a data object which is then passed to the work routine. This is not supported in the Java API.

../_images/remote-service-execution-diagram.png

Take these things into account when implementing remote services:

  • Access the Kanzi Connect API, including property updates, only from the main thread context.

    For example, if you need a periodic operation, create a dedicated thread that periodically invokes the notifyWork method of AbstractService.

  • If you need parallelization in the method handling of the service, execute long-lasting operations in worker threads.

  • ClientRemoteServiceHost can handle only one service at a time. If you need the remote process to provide multiple services to a server, it needs to form multiple parallel connections.