Skip to content

Latest commit

 

History

History
297 lines (204 loc) · 10.4 KB

api-runtime.md

File metadata and controls

297 lines (204 loc) · 10.4 KB
Raw

Runtime Component

Introduction

Runtime is component that provides container-based abstraction for Threads and Processes and means of managing and supervising children containers from its ancestor level.

Features

Runtime features:

- Container-based (actor-based) abstraction for Threads and Processes - Separation between standard and emergent flow of business logic inside single container - Command-based controls to pass orders between containers - Built-in Process local and remote managers - Built-in Thread local and remote managers - Built-in Runtime managers abstracting managment of processes and threads - Supervision mechanisms with separation of local and remote errors - Supervision problem solvers - Kraken Framework compatibility

Concepts

This section contains terminology, useful concepts and definitions, that might be helpful to learn to fully understand this component purpose.

Runtime

Runtime is a common name for both process or thread created by Kraken. It is an abstractions that allows operating on them using single interface.

Container

Container is an instance of any given runtime that contains both runtime's logic and all of its services. Container is Kraken's implementation of an actor.

You can read more about runtimes in runtimes article.

Examples

This section contains examples and patterns that can be used with described component.

Changing The State

Changing the state of runtime might be done via start and stop methods.

// this will emit application-wide "start" event
$container->start(); 

// this will emit application-wide "stop" event
$container->stop();

{warning} There exists also create and destroy methods, however you must never call them directly, as using them directly might danger your application integrity.

{notice} The start and stop methods are designed mainly for your application logic to respond to container downtimes and uptimes. Kraken internal services does not react to them, as they have to work anyway.

Registering Listeners

There are many of events thrown by container during its lifecycle. You can view them in Kraken\Runtime\RuntimeContainerInterface. The most important two are start and stop.

$container->onStart(function() {
    // do something on container start
});

$container->onStop(function() {
    // do something on container stop
});

Getting Context

The container interface extends Kraken\Runtime\RuntimeContextInterface so you are able to use methods such as getType, getParent, getAlias, getName and getArgs for getting all information about current container context.

Getting alias example:

$alias = $runtime->getAlias();

Getting State

The container's state might be fetched using following syntax:

$state = $runtime->getState();

Triggering The Supervisor

Triggering supervisor will force your container to stop application logic and enter failed state. You can read more about this in supervision article. To trigger the supervision use fail method.

$runtime->fail($exception, $params);

Creating & Destroying Children

Creating and destroying the children might be done using create and destroy prefixed method of Kraken\Runtime\RuntimeManagerInterface. All these methods implements Kraken\Promise\PromiseInterface.

Creating Process

$manager = $runtime->getManager();
$manager
    ->createProcess($alias, $name, $flags)
    ->done(function() {
        echo "Process has been created!\n";
    });

Creating Thread

$manager = $runtime->getManager();
$manager
    ->createThread($alias, $name, $flags)
    ->done(function() {
        echo "Thread has been created!\n";
    });

Destroying Process

$manager = $runtime->getManager();
$manager
    ->destroyProcess($alias, $name, $flags)
    ->done(function() {
        echo "Process has been destroyed!\n";
    });

Destroying Thread

$manager = $runtime->getManager();
$manager
    ->destroyThread($alias, $name, $flags)
    ->done(function() {
        echo "Thread has been destroyed!\n";
    });

{tip} Some of the process and thread related methods can be abstracted via runtime related methods that works with both of them. The only abstraction which is not provided by runtime methods is creation of containers, as you have to specify exactly what kind of runtime you want to invoke.

Starting & Stopping Children

Starting and stopping the children might be done in similar way as creating and destroying them. The difference is that you have to use start and stop prefixed methods:

Starting Container

$manager = $runtime->getManager();
$manager
    ->startRuntime($alias, $name, $flags)
    ->done(function() {
        echo "Container has been started!\n";
    });

Stopping Container

$manager = $runtime->getManager();
$manager
    ->stopRuntime($alias, $name, $flags)
    ->done(function() {
        echo "Container has been stopped!\n";
    });

{tip} Some of the process and thread related methods can be abstracted via runtime related methods that works with both of them. The only abstraction which is not provided by runtime methods is creation of containers, as you have to specify exactly what kind of runtime you want to invoke.

Sending Messages

Sending messages to runtime container's children might be done via:

$manager = $runtime->getManager();
$manager->sendMessage($alias, $message, $flags);

Sending Requests

Sending requests to runtime container's children might be done via:

$manager = $runtime->getManager();
$manager
    ->sendRequest($alias, $message, $params)
    ->done(function($result) {
        printf("Received response = \"%s\"\n", $result);
    });

Invoking Remote Commands

Remote commands might be invoked on runtime container's children using following syntax:

$manager = $runtime->getManager();
$manager
    ->sendCommand($alias, $commandName, $commandParams)
    ->done(function($result) {
        printf("Received response = \"%s\"\n", $result);
    });

Important Classes & Interfaces

This section contains list of most important classes and interfaces shipped with this component. It does not include all classes and interface.

RuntimeContainer

class RuntimeContainer extends EventEmitter implements RuntimeContainerInterface

RuntimeContainer is a concrete class that contains all internal data of container including the context and the core, it also works as container controller.

RuntimeContainerInterface

interface RuntimeContainerInterface extends RuntimeContextInterface, CoreGetterAwareInterface, EventEmitterInterface, LoopGetterAwareInterface

RuntimeModel

class RuntimeModel implements RuntimeModelInterface

RuntimeModel is internal implementation working behind RuntimeContainer class.

RuntimeModelInterface

interface RuntimeModelInterface extends RuntimeContextInterface, RuntimeManagerAwareInterface, SupervisorAwareInterface, CoreAwareInterface, EventEmitterAwareInterface, LoopExtendedAwareInterface

RuntimeContextInterface

interface RuntimeContextInterface

RuntimeContextInterface is an interface providing set o methods for accessing container's context information.

RuntimeCommand

class RuntimeCommand

RuntimeCommand is a class that have to be used when invoking remote commands between containers using their channels.

RuntimeManager

class RuntimeManager implements RuntimeManagerInterface

RuntimeManager is a class that allows managing container's children.

RuntimeManagerInterface

interface RuntimeManagerInterface extends ProcessManagerInterface, ThreadManagerInterface

Important Directories

This section contains list of most important directories existing inside of component. It does not include all directories.

Command

Command folder contains pre-defined container-related commands.

Container

Container folder contains internal logic working behind runtimes abstraction and useful container-related classes such as controllers and managers.

Supervision

Supervision folder contains pre-defined problem solvers.