jina.peapods.runtimes.base module

class jina.peapods.runtimes.base.BaseRuntime(args, ready_event, **kwargs)[source]

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 acts as a multiprocessing.Process or threading.Thread, it starts from M and once the S is spawned, it calls Runtime methods in the following order:

  1. __init__()

1. run_forever(). Note that this will block S, step 3 won’t be reached until it is unblocked by cancel(). This method is responsible to set the ready_event to guarantee that the rest of the system knows when it is ready to receive messages.

2. 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 __init__() and teardown() pair together, which defines instructions that will be executed before and after. In subclasses, teardown is 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().


Rule of thumb on exception handling: if you are not sure if you should handle exception inside run_forever(), cancel(), 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.


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


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

See also

cancel() for cancelling the forever loop.


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