The low-level Python/C interface
================================

.. module:: ktlc

The :mod:`ktlc` module is the sole interface between the :mod:`ktl` module
and the underlying KTL/C API. The operations performed in this module strive
to be the absolute minimum required to cleanly wrap calls to the KTL/C API;
complex operations are better handled in the :mod:`ktl` module, as mistakes
in the Python half tend to be less subtle, easier to correct, and more
straight-forward to test.

Because all calls to the :mod:`ktlc` module are filtered by an :class:`Usher`
thread, no great effort was made to ensure thread-safety internal to the module
itself. On the contrary, the only concessions made by the :mod:`ktlc` module
to thread-awareness are to release the Python interpreter to execute other
threads if a KTL call will obviously block, such as a ``KTL_WAIT`` invocation
of :func:`read` or :func:`write`.


Functions
---------

.. autofunction:: dumpster (append, stop)
.. autofunction:: probe (service, keyword)
.. autofunction:: logFunction (function)
.. autofunction:: loglevel (level=None)


Classes
-------

.. autoclass:: Service

   .. automethod:: descriptors
   .. automethod:: dispatch
   .. automethod:: headers
   .. automethod:: list

   Significant attributes of the :class:`Service` class:

   .. autoattribute:: name
   .. autoattribute:: notify


.. autoclass:: Keyword

   .. automethod:: monitor (callback)
   .. automethod:: range ()
   .. automethod:: read ()
   .. automethod:: servers ()
   .. automethod:: units ()
   .. automethod:: write (value, binary, wait, callback)

   Significant attributes of the :class:`Keyword` class:

    .. autoattribute:: broadcasts
    .. autoattribute:: name
    .. autoattribute:: monitored
    .. autoattribute:: notify
    .. autoattribute:: reads
    .. autoattribute:: service
    .. autoattribute:: type
    .. autoattribute:: writes


.. autoclass:: Trash
   :members: