/*
 * This file is part of the StarPU Handbook.
 * Copyright (C) 2009--2011  Universit@'e de Bordeaux
 * Copyright (C) 2010, 2011, 2012, 2013, 2014, 2017  CNRS
 * Copyright (C) 2011, 2012 INRIA
 * See the file version.doxy for copying conditions.
 */

/*! \defgroup API_StarPUTop_Interface StarPU-Top Interface

\enum starpu_top_data_type
\ingroup API_StarPUTop_Interface
StarPU-Top Data type
\var starpu_top_data_type::STARPU_TOP_DATA_BOOLEAN
    todo
\var starpu_top_data_type::STARPU_TOP_DATA_INTEGER
    todo
\var starpu_top_data_type::STARPU_TOP_DATA_FLOAT
    todo

\enum starpu_top_param_type
\ingroup API_StarPUTop_Interface
StarPU-Top Parameter type
\var starpu_top_param_type::STARPU_TOP_PARAM_BOOLEAN
    todo
\var starpu_top_param_type::STARPU_TOP_PARAM_INTEGER
    todo
\var starpu_top_param_type::STARPU_TOP_PARAM_FLOAT
    todo
\var starpu_top_param_type::STARPU_TOP_PARAM_ENUM
    todo

\enum starpu_top_message_type
\ingroup API_StarPUTop_Interface
StarPU-Top Message type
\var starpu_top_message_type::TOP_TYPE_GO
    todo
\var starpu_top_message_type::TOP_TYPE_SET
    todo
\var starpu_top_message_type::TOP_TYPE_CONTINUE
    todo
\var starpu_top_message_type::TOP_TYPE_ENABLE
    todo
\var starpu_top_message_type::TOP_TYPE_DISABLE
    todo
\var starpu_top_message_type::TOP_TYPE_DEBUG
    todo
\var starpu_top_message_type::TOP_TYPE_UNKNOW
    todo

\struct starpu_top_data
todo
\ingroup API_StarPUTop_Interface
\var unsigned int starpu_top_data::id
    todo
\var const char *starpu_top_data::name
    todo
\var int starpu_top_data::int_min_value
    todo
\var int starpu_top_data::int_max_value
    todo
\var double starpu_top_data::double_min_value
    todo
\var double starpu_top_data::double_max_value
    todo
\var int starpu_top_data::active
    todo
\var enum starpu_top_data_type starpu_top_data::type
    todo
\var struct starpu_top_data *starpu_top_data::next
    todo

\struct starpu_top_param
todo
\ingroup API_StarPUTop_Interface
\var unsigned int starpu_top_param::id
    todo
\var const char *starpu_top_param::name
    todo
\var enum starpu_top_param_type starpu_top_param::type
    todo
\var void *starpu_top_param::value
    todo
\var char **starpu_top_param::enum_values
    only for enum type can be <c>NULL</c>
\var int starpu_top_param::nb_values
    todo
\var void (*starpu_top_param::callback)(struct starpu_top_param*)
    todo
\var int starpu_top_param::int_min_value
    only for integer type
\var int starpu_top_param::int_max_value
    todo
\var double starpu_top_param::double_min_value
    only for double type
\var double starpu_top_param::double_max_value
    todo
\var struct starpu_top_param *starpu_top_param::next
    todo

@name Functions to call before the initialisation
\ingroup API_StarPUTop_Interface

\fn struct starpu_top_data *starpu_top_add_data_boolean(const char *data_name, int active)
\ingroup API_StarPUTop_Interface
Register a data named \p data_name of type boolean.
If \p active is 0, the value will NOT be displayed to users.
Any other value will make the value displayed.

\fn struct starpu_top_data *starpu_top_add_data_integer(const char *data_name, int minimum_value, int maximum_value, int active)
\ingroup API_StarPUTop_Interface
Register a data named \p data_name of type integer. \p minimum_value
and \p maximum_value will be used to define the scale in the UI.
If \p active is 0, the value will NOT be displayed to users.
Any other value will make the value displayed.

\fn struct starpu_top_data *starpu_top_add_data_float(const char *data_name, double minimum_value, double maximum_value, int active)
\ingroup API_StarPUTop_Interface
Register a data named \p data_name of type float. \p minimum_value and
\p maximum_value will be used to define the scale in the UI.
If \p active is 0, the value will NOT be displayed to users.
Any other value will make the value displayed.

\fn struct starpu_top_param *starpu_top_register_parameter_boolean(const char *param_name, int *parameter_field, void (*callback)(struct starpu_top_param*))
\ingroup API_StarPUTop_Interface
Register a parameter named \p parameter_name, of type
boolean. If not \c NULL, the \p callback function will be called when
the parameter is modified by the UI.

\fn struct starpu_top_param *starpu_top_register_parameter_float(const char *param_name, double *parameter_field, double minimum_value, double maximum_value, void (*callback)(struct starpu_top_param*))
\ingroup API_StarPUTop_Interface
Register a parameter named \p param_name, of type
integer. \p minimum_value and \p maximum_value will be used to prevent
users from setting incorrect value. If not \c NULL, the \p callback
function will be called when the parameter is modified by the UI.

\fn struct starpu_top_param *starpu_top_register_parameter_integer(const char *param_name, int *parameter_field, int minimum_value, int maximum_value, void (*callback)(struct starpu_top_param*))
\ingroup API_StarPUTop_Interface
Register a parameter named \p param_name, of type float.
\p minimum_value and \p maximum_value will be used to prevent users
from setting incorrect value. If not \c NULL, the \p callback function
will be called when the parameter is modified by the UI.

\fn struct starpu_top_param *starpu_top_register_parameter_enum(const char *param_name, int *parameter_field, char **values, int nb_values, void (*callback)(struct starpu_top_param*))
\ingroup API_StarPUTop_Interface
Register a parameter named \p param_name, of type enum.
\p values and \p nb_values will be used to prevent users from setting
incorrect value. If not \c NULL, the \p callback function will be
called when the parameter is modified by the UI.

@name Initialisation
\ingroup API_StarPUTop_Interface

\fn void starpu_top_init_and_wait(const char *server_name)
\ingroup API_StarPUTop_Interface
Must be called when all parameters and data have been
registered AND initialised (for parameters). It will wait
for a TOP to connect, send initialisation sentences, and wait for the
GO message.

@name To call after initialisation
\ingroup API_StarPUTop_Interface

\fn void starpu_top_update_parameter(const struct starpu_top_param *param)
\ingroup API_StarPUTop_Interface
Should be called after every modification of a parameter
from something other than starpu_top. It notices the UI that the
configuration has changed.

\fn void starpu_top_update_data_boolean(const struct starpu_top_data *data, int value)
\ingroup API_StarPUTop_Interface
Update the boolean value of \p data to \p value the UI.

\fn void starpu_top_update_data_integer(const struct starpu_top_data *data, int value)
\ingroup API_StarPUTop_Interface
Update the integer value of \p data to \p value the UI.

\fn void starpu_top_update_data_float(const struct starpu_top_data *data, double value)
\ingroup API_StarPUTop_Interface
Update the float value of \p data to \p value the UI.

\fn void starpu_top_task_prevision(struct starpu_task *task, int devid, unsigned long long start, unsigned long long end)
\ingroup API_StarPUTop_Interface
Notift the UI that \p task is planned to run from \p start to \p end, on computation-core.

\fn void starpu_top_debug_log(const char *message)
\ingroup API_StarPUTop_Interface
When running in debug mode, display \p message in the UI.

\fn void starpu_top_debug_lock(const char *message)
\ingroup API_StarPUTop_Interface
When running in debug mode, send \p message to the UI and wait for a
continue message to return. The lock (which creates a stop-point) should be
called only by the main thread. Calling it from more than one thread
is not supported.

*/