jina.peapods.runtimes.base

class jina.peapods.runtimes.base.BaseRuntime(args)

Bases: object

A Jina Runtime is a procedure that blocks the main process once running (i.e. run_forever()), therefore must be put into a separated thread/process. Any program/library/package/module that blocks the main process, can be formulated into a BaseRuntime class and then be used in BasePea.

In the sequel, we call the main process/thread as M, the process/thread blocked Runtime as S.

In Jina, a BasePea object is used to manage a Runtime object’s lifecycle. A BasePea is a subclass of multiprocessing.Process or threading.Thread, it starts from M and once the S is spawned, it calls Runtime methods in the following order:

0. __init__() in M

1. setup() in S

2. run_forever() in S. Note that this will block S, step 3 won’t be reached until it is unblocked by cancel()

3. teardown() in S. Note that S is blocked by run_forever(), this step won’t be reached until step 2 is unblocked by cancel()

The setup() and teardown() pair together, which defines instructions that will be executed before and after. In subclasses, they are optional.

The run_forever() and cancel() pair together, which introduces blocking to S and then unblocking from it. They are mandatory for all subclasses.

Note that, there is no “exclusive” relation between run_forever() and teardown(), teardown() is not about “cancelling”, it is about “cleaning”.

Unlike other three methods that get invoked inside S, the cancel() is invoked in M to unblock S. Therefore, cancel() usually requires some special communication between M and S, e.g.

• Use threading.Event or multiprocessing.Event, while run_forever() polls for this event

• Use ZMQ to send a message, while run_forever() polls for this message

• Use HTTP/REST to send a request, while run_forever() listens to this request

Note, another way to jump out from run_forever() is raise exceptions from it. This will immediately move to teardown().

Note

Rule of thumb on exception handling: if you are not sure if you should handle exception inside run_forever(), cancel(), setup(), teardown(), then DO NOT catch exception in them. Exception is MUCH better handled by BasePea.

See also

BasePea for managing a Runtime object’s lifecycle.

run_forever()

Running the blocking procedure inside S. Note, once this method is called, S is blocked.

Note

If this method raises any exception, teardown() will be called.

See also

cancel() for cancelling the forever loop.

cancel()

Cancelling run_forever() from M. cancel() usually requires some special communication between M and S, e.g.

• Use threading.Event or multiprocessing.Event, while run_forever() polls for this event

• Use ZMQ to send a message, while run_forever() polls for this message

• Use HTTP/REST to send a request, while run_forever() listens to this request

See also

run_forever() for blocking the process/thread.

setup()

Method called to prepare the runtime inside S. Optional in subclasses. The default implementation does nothing.

Note

If this method raises any exception, then run_forever() and teardown() won’t be called.

Note

Unlike __init__() called in M, setup() is called inside S.

teardown()

Method called immediately after run_forever() is unblocked. You can tidy up things here. Optional in subclasses. The default implementation does nothing.

Note

This method will only be called if the setup() succeeds.