Moved lock submodule into 'common' and updated docs

Common utilities

=======================================================

Tasks module

------------

.. automodule:: openflexure_microscope.common.tasks

    :members:

Lock module

-----------

.. automodule:: openflexure_microscope.common.lock

    :members:

 No newline at end of file

   config.rst

   microscope.rst

   camera.rst

   common.rst

   plugins.rst

   api.rst

.. autoclass:: openflexure_microscope.api.v1.views.MicroscopeViewPlugin

    :members:

Task module

-----------

.. automodule:: openflexure_microscope.task

    :members:

Lock module

-----------

.. automodule:: openflexure_microscope.lock

    :members:

Default plugins

---------------

from openflexure_microscope.api.v1.views import MicroscopeViewPlugin

from openflexure_microscope.api.utilities import JsonResponse

from openflexure_microscope.common.tasks import taskify

import os

import time

import json

        n_images = payload.param("n_images", default=10, convert=int)

        # Attach the long-running method as a microscope task

        self.timelapse_task = self.microscope.task.start(

            self.plugin.timelapse, n_images

        )

        self.timelapse_task = taskify(self.plugin.timelapse)(n_images)

        # Return the state of the task (will show ID, start time, and status before the task has finished)

        return jsonify(self.timelapse_task.state), 202

the use of tasks, long-running functions would block an HTTP response until the function returns, often 

resulting in a timeout.

To prevent this, any function can be offloaded to a background task. This is done through the microscope's ``task`` object,

by calling ``<microscope>.task.start(<long_running_function>, *args, **kwargs)``. Internally, the ``task`` object stores a list

To prevent this, any function can be offloaded to a background task. This is done through the :py:meth:`openflexure_microscope.common.tasks.taskify` 

function, by calling ``taskify(<long_running_function>)(*args, **kwargs)``. Internally, the ``tasks`` submodule stores a list

of all requested tasks, which themselves contain a ``state`` dictionary. This dictionary stores the status of the task (if it

is idle, running, error, or success), information about the start and end times, a unique task ID, and the return value of 

the long-running function. 

.. code-block:: python

    from openflexure_microscope.plugins import MicroscopeViewPlugin

    from openflexure_microscope.exceptions import TaskDeniedException

    from openflexure_microscope.common.tasks import taskify

    class MyPlugin(MicroscopeViewPlugin):

        def post(self):

            # Attach the long-running method as a microscope task

            try:

                self.my_task = self.microscope.task.start(self.plugin.long_running_function)

            self.my_task = taskify(self.plugin.long_running_function)()

            return jsonify(self.my_task.state), 202

            except TaskDeniedException:

                return abort(409)

After some time, once the task has completed, it could be retreived using:

.. code-block:: python

within a tile scan), another user should not be able to move the microscope, interrupting the task. Thread locks act

to prevent this.

The camera and stage both contain an instance of :py:class:`openflexure_microscope.lock.StrictLock`, named ``lock``.

The camera and stage both contain an instance of :py:class:`openflexure_microscope.common.lock.StrictLock`, named ``lock``.

Built-in functions such as capture and move will always acquire this lock for the duration of the function. This ensures

that, for example, simultaneous attemps to move do not occur.