.. _callback-example:

Using Callbacks
===============

Callbacks can be used instead of or in addition to busy-wait 
loops to get notification that an asynchronous OpenAPI function has
completed the requested action. 

Callbacks are required for
handling unpredictable communications from the DBMS, such as 
various kinds of trace messages (I/O, logging, etc.) and notifications
of database events
(DBEvents).

When a callback is specified using the :attr:`!IIAPI_GENPARM` 
structure of an OpenAPI asynchronous function control block, 
the :attr:`!gp_callback` attribute is the address of the
callback function, and :attr:`!gp_closure` can be a pointer to a 
an optional value that will be passed to the callback as an argument.

Closure is the means by which an application passes information 
to the callback function.

Callback functions are expected to take two arguments. The first 
is expected to be a pointer to the closure, and the second is expected
to be a pointer to an :attr:`!IIAPI_GENPARM` structure.

Callbacks can't return a value, but if passed a pointer to a structure as the
closure they can update its contents. They can also update globals. 

..  NOTE::

    This example makes use of the :func:`!IIapi_getCallbackPtr`
    and :func:`!IIapi_getClosure` helper 
    functions provided by ``pyngres``. They are not part of the 
    Actian OpenAPI.

..  TIP::

    Refer to the ``ctypes`` `documentation <https://docs.python.org/3/library/ctypes.html#callback-functions>`_ for additional explanation of callbacks.
    
:download:`Download <./examples/callback.py>`

..  LITERALINCLUDE:: ./examples/callback.py
    :linenos:

:download:`Download <./examples/callback.py>`