fleche.executor
===============

.. py:module:: fleche.executor

.. autoapi-nested-parse::

   Executor wrapper that intercepts ``submit`` for fleche-decorated functions.

   Motivation: users passing a :func:`fleche.fleche`-decorated function to
   ``executor.submit(...)`` have to remember to call :meth:`.BoundWrapper.bind`
   themselves to carry the active cache/metadata state into the worker.  They also
   pay the submit/serialisation cost even when the result is already cached.

   :func:`wrap_executor` patches the ``submit`` method of an executor *instance*
   (we cannot subclass, since callers pass us instances of third-party executors)
   so that:

   * non-fleche callables are forwarded unchanged,
   * fleche callables whose result is already cached are returned via an
     already-completed :class:`~concurrent.futures.Future` without touching the
     executor, and
   * otherwise the call is bound via :meth:`.BoundWrapper.bind` and submitted to
     the original ``submit``.

   Executors that declare their own keyword-only parameters on ``submit``
   (e.g. ``resources=`` or ``resource_dict=``) have those split off from the
   caller's ``**kwargs`` and forwarded to the underlying ``submit`` while the
   remaining keyword arguments are bound as part of the function payload.



Functions
---------

.. autoapisummary::

   fleche.executor.wrap_executor


Module Contents
---------------

.. py:function:: wrap_executor(executor)

   Monkey-patch ``executor.submit`` to intercept fleche-wrapped functions.

   Calling :func:`wrap_executor` on an executor that is already wrapped is a
   no-op: the patch is not stacked, and the original ``submit`` continues to
   refer to the pre-wrap method.

   :param executor: any object with a ``submit(func, *args, **kwargs)`` method
                    (e.g. :class:`concurrent.futures.Executor` subclass instances).

   :returns: The same ``executor`` instance, with a replaced ``submit`` attribute.