Usage
=====

Including the API
-----------------

Include the header file in your C source:

.. code-block:: c

    #include "dtg_api.h"

Implementing User Functions
---------------------------

Implement the required callback functions. For example:

.. code-block:: c

    int my_init(dtg_task_t *task) {
        // Initialization code
        return 0;
    }

    int my_task(dtg_task_t *task) {
        // Task execution code
        return 0;
    }

    int my_fini(dtg_task_t *task) {
        // Finalization code
        return 0;
    }

Using Task Functions
--------------------

Within your user functions, you can use the API functions to interact with the task:

.. code-block:: c

    int my_task(dtg_task_t *task) {
        // Store application-specific state
        task->user_data = my_state_ptr;

        // Set a key-value pair
        dtg_task_set_col(task, "status", "running");

        // Get a value
        char buf[256];
        int flag;
        dtg_task_get_val(task, "input", buf, sizeof(buf), &flag);

        // Adapt the task if needed
        int term, resized;
        dtg_task_adapt(task, &term, &resized);

        return 0;
    }

Note:

- ``task->user_data`` can be used to store application-defined per-task state.
- ``task->library_data`` is reserved for internal DTG library use and should not be modified by user code.

Linking the Library
-------------------

When compiling your application, link against the DTG library and its dependencies:

.. code-block:: bash

    gcc -o myapp myapp.c -ldtg -lmpi -ldyn_psets -ljansson

Running the Application
-----------------------

Run your MPI application as usual, ensuring the DTG library is properly initialized by the library's internal mechanisms.