/**
 * @file include/di_fw/periodic.h
 * @brief periodic cooperative tasks
 * @date September 1, 2016
 * @author A.A.W.M. Ruijs
 * @copyright 2016 Dual Inventive Technology Centre B.V.
 *
 * Periodic is used to keep track of actions that need to be done in a set interval.
 * @note Periodic is not hard-realtime due to cooperative task selection and previous
 *       tasks can take a significant amount of time. You could expect a deviation of
 *       100 milliseconds or more.
 */
#ifndef INCLUDE_PERIODIC_H__
#define INCLUDE_PERIODIC_H__

#include <stdint.h>

#include <di_fw/os.h>
#include <di/semaphore.h>
#include <di/types.h>

/**
 * Periodic event
 */
struct di_fw_periodic_event {
	uint64_t interval_ms; /**< Interval */
	uint64_t deadline;    /**< Deadline */
	bool oneshot;         /**< Oneshot */
	void *private_data;   /**< Event specific data */
	void (*action)(struct di_fw_periodic_event *ev);   /**< Callback */
};

/*
 * periodic context
 */
struct di_fw_periodic_ctx {
	struct di_fw_periodic_event *event;
	size_t size;
	di_bsem_t lock;
};

/**
 * Initialize periodic item with first deadline
 */
void di_fw_periodic_init(void);

/**
 * Add a new periodic event to the event list with the given parameters.
 * @note the first event will be fired right after the call. Consecutive events will be fired
 * with <interval_ms> miliseconds in between
 *
 * @param id            pointer where the id will be written to
 * @param interval_ms   interval in miliseconds how often the events need to be triggered
 * @param action        the action that needs to be done every interval
 * @param private_data  possible data that is needed for the action
 *
 * @return DNOK if event is added
 * @return DNE_NORES if event can not be added
 */
di_errno_t di_fw_periodic_add_event(uint32_t *id, const uint64_t interval_ms,
				    void (*action)(struct di_fw_periodic_event *ev), void *private_data);
/**
 * Add a new oneshot event to the event list with the given parameters.
 * A oneshot event callback will be fired after the requested interval and is fired only once
 * The event will automatically be removed from the event list after it has fired
 * @note the first and only event will be fired after <interval_ms> > miliseconds have elapsed
 *
 * @param interval_ms   oneshot interval in miliseconds
 * @param action        the action that needs to be executed after the interval elapsed
 * @param private_data  possible data that is needed for the action
 *
 * @return DNOK if event is added
 * @return DNE_NORES if event can not be added
 */
di_errno_t di_fw_periodic_add_oneshot(const uint64_t interval_ms, void (*action)(struct di_fw_periodic_event *ev),
				      void *private_data);

/**
 * Delete periodic event from the list
 * @note Call of this function is only allowed from within a periodic callback (bsem is locked then)
 */
void di_fw_periodic_del_event(struct di_fw_periodic_event *ev);

/**
 * Fire event next time it is checked.
 * @param id id of the event that needs to be fired
 */
void di_fw_periodic_fire_event(uint32_t id);

/**
 * Set new interval for periodic event, it recalculates the new deadline.
 * @param e		pointer to the event
 * @param interval_ms	new interval for the event
 */
void di_fw_periodic_set_interval(struct di_fw_periodic_event *e, uint64_t interval_ms);

#endif /* LIBDI_FW_PERIODIC_H__ */