.. _callback function:

2.4 Callback Function
==============================================

This section describes the callback function types supported by the DRFL.
Callback definitions specify the function signatures used for event-driven communication, allowing user applications to receive asynchronous robot updates such as logging, monitoring data, and safety events.

.. toctree::
   :maxdepth: 1

   core_state_lifecycle/core_state_lifecycle
   monitoring_streams/monitoring_streams

   io_modbus_comm/io_modbus_comm

   safety_system_access/safety_system_access
   
   tp_ui_message/tp_ui_message

   rt_stream/rt_stream
   welding_data/welding_data

.. _callback_rules:

Rules for callback functions
------------------------------------------

The library calls each callback automatically when its event occurs. Keep the code inside a callback short and return well within one data period (100 ms before DRCF 3.5, 20 ms from DRCF 3.5); copy the data you need and process it outside the callback. The RT callback :ref:`TOnRTMonitoringDataCB <cb_tonrtmonitoringdatacb>` uses the output period set with :ref:`set_rt_control_output <set_rt_control_output>` instead of the data period.

Do not call a function that waits for data from the controller (for example ``get_current_posx``, ``get_desired_posx``, ``fkin``, ``ikin``, ``trans``, ``coord_transform``, ``get_user_home``) or ``drl_stop`` inside a state, alarm, access-control, TP, mastering, program-stopped, safety-state, safety-stop-type, robot-system, homing or TP-initializing callback: the call does not return, and no further callbacks are delivered. ``get_system_version`` called there returns false after about 5 seconds. Commands that only wait for the controller to accept them (for example ``set_robot_mode`` and ``move_home``) return when the controller answers; if no answer arrives within about 6 seconds, they return true although the controller did not confirm the command. Every one of these calls holds the callback while it waits. Copy the data you need and process it outside the callback. These callbacks are called one after another, so a slow callback delays the ones after it.

Callback functions must not let exceptions escape. Catch all exceptions inside the callback.

A CDRFLEx object does not support concurrent calls. Make the calls on one object one at a time, including calls made from callbacks.

When a connection ends (``close_connection``, loss of connection, or ``open_connection`` on an object that is already connected), every callback registered with a ``set_on_*`` function is unregistered, except those registered with ``set_on_disconnected``, ``set_on_monitoring_ctrl_io_ex`` (with DRCF_VERSION 3, the default), ``set_on_rt_monitoring_data`` and ``set_on_rt_log_alarm``, which stay registered. After each successful ``open_connection``, register the other callbacks again and call ``setup_monitoring_version`` again.