Metadata-Version: 2.0
Name: backend.ai-kernel-runner
Version: 1.0.3
Summary: User code executors for Backend.AI kernels
Home-page: https://github.com/lablup/backend.ai-kernel-runner
Author: Lablup Inc.
Author-email: joongi@lablup.com
License: MIT
Description-Content-Type: UNKNOWN
Platform: UNKNOWN
Classifier: License :: OSI Approved :: MIT License
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Operating System :: POSIX
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Environment :: No Input/Output (Daemon)
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development
Requires-Python: >=3.6
Requires-Dist: async-timeout (>=1.1)
Requires-Dist: aiozmq (>=0.7)
Requires-Dist: uvloop (>=0.8)
Requires-Dist: simplejson
Requires-Dist: namedlist
Requires-Dist: janus
Requires-Dist: msgpack-python
Provides-Extra: build
Requires-Dist: wheel; extra == 'build'
Requires-Dist: twine; extra == 'build'
Provides-Extra: c
Provides-Extra: ci
Provides-Extra: cpp
Provides-Extra: dev
Requires-Dist: wheel; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Requires-Dist: pytest (>=3.1); extra == 'dev'
Requires-Dist: pytest-asyncio; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest-mock; extra == 'dev'
Requires-Dist: asynctest; extra == 'dev'
Requires-Dist: flake8; extra == 'dev'
Requires-Dist: codecov; extra == 'dev'
Requires-Dist: pytest-sugar; extra == 'dev'
Provides-Extra: git
Provides-Extra: golang
Provides-Extra: haskell
Provides-Extra: java
Provides-Extra: julia
Provides-Extra: lua
Provides-Extra: nodejs
Provides-Extra: octave
Provides-Extra: php
Provides-Extra: python
Requires-Dist: six; extra == 'python'
Requires-Dist: IPython; extra == 'python'
Requires-Dist: pandas; extra == 'python'
Requires-Dist: numpy; extra == 'python'
Requires-Dist: matplotlib; extra == 'python'
Provides-Extra: r
Provides-Extra: rust
Provides-Extra: test
Requires-Dist: pytest (>=3.1); extra == 'test'
Requires-Dist: pytest-asyncio; extra == 'test'
Requires-Dist: pytest-cov; extra == 'test'
Requires-Dist: pytest-mock; extra == 'test'
Requires-Dist: asynctest; extra == 'test'
Requires-Dist: flake8; extra == 'test'
Requires-Dist: codecov; extra == 'test'

Backend.AI Kernel Runner
========================

A common base runner for various programming languages.

It manages an internal task queue so that multiple command/code execution requests
are processed in the FIFO order, without garbling the console output.


How to write a new computation kernel
-------------------------------------

Inherit ``ai.backend.kernel.BaseRunner`` and implement the following methods:

* ``async def init_with_loop(self)``

  - Called after the asyncio event loop becomes available.

  - Mostly just ``pass``.

  - If your kernel supports interactive user input, then put set
    ``self.user_input_queue`` as an ``asyncio.Queue`` object.  It's your job
    to utilize the queue object for waiting for the user input.  (See
    ``handle_input()`` method in ``ai/backend/kernel/python/inproc.py`` for
    reference)  If it's not set, then any attempts for getting interactive user
    input will simply return ``"<user-input is unsupported>"``.

* ``async def build_heuristic(self)``

  - *(Batch mode)* Write a heuristic code to find some build script or run a
    good-enough build command for your language/runtime.

  - *(Blocking)* You don't have to worry about overlapped execution since the
    base runner will take care of it.

* ``async def execute_heuristic(self)``

  - *(Batch mode)* Write a heuristic code to find the main program.

  - *(Blocking)* You don't have to worry about overlapped execution since the
    base runner will take care of it.

* ``async def query(self, code_text)``

  - *(Query mode)* Directly run the given code snippet. Depending on the language/runtime,
    you may need to create a temporary file and execute an external program.

  - *(Blocking)* You don't have to worry about overlapped execution since the
    base runner will take care of it.

* ``async def complete(self, data)``

  - *(Query mode)* Take a dict data that includes the current line of code where
    the user is typing and return a list of strings that can auto-complete it.

  - *(Non-blocking)* You should implement this method to run asynchronously with
    ongoing code execution.

* ``async def interrupt(self)``

  - *(Query mode)* Send an interruption signal to the running program. The implementation
    is up to you. The Python runner currently spawns a thread for in-process
    query-mode execution and use a ctypes hack to throw KeyboardInterrupt
    exception into it.

  - *(Non-blocking)* You should implement this method to run asynchronously with
    ongoing code execution.


NOTE: Existing codes are good referecnes!


How to use in your Backend.AI computation kernels
-------------------------------------------------

Install this package using pip via a ``RUN`` instruction in Dockerfile.
Then, set the ``CMD`` instruction like below:

.. code-block:: dockerfile

   CMD ["/home/sorna/jail", "-policy", "/home/sorna/policy.yml", \
        "/usr/local/bin/python", "-m", "ai.backend.kernel", "<language>"]

where ``<language>`` should be one of the supported language names defined in
``lang_map`` variable in ``ai/backend/kernel/__main__.py`` file.


