cx-zivuos/headers/zivuos/event.h

#ifndef CX_ZIVUOS_EVENT_H_INCLUDED
#define CX_ZIVUOS_EVENT_H_INCLUDED

#include "zv_types.h"
#include "event_type.h"
#include "zv_time.h"

/**
 * @brief List of event types.
 * 
 * That enum is used to store type of the event. Default event is empty,
 * which mean that no event occur.
 */
typedef enum zv_event_type_e {
    
    /* That mean no event occur. */
    ZV_EVENT_EMPTY,

    /* That mean event is timer, whose waiting time has already expired. */
    ZV_EVENT_TIMER,
    
    /* 
     * That mean timer event is waiting in first phrase, it is used by 
     * scheduler for timer processing.
     */
    ZV_EVENT_TIMER_PHRASE_FIRST,

    /* 
     * That mean timer event is waiting in second phrase, it is used by 
     * scheduler for timer processing.
     */
    ZV_EVENT_TIMER_PHRASE_SECOND,

    /* That mean event with data occured. */
    ZV_EVENT_DATA,

    /* That mean event with unsigned data occured. */
    ZV_EVENT_UDATA,

    /* That mean event with object pointer occured. */
    ZV_EVENT_OBJECT,

} zv_event_type_t;


/**
 * @brief That store content of the event.
 * 
 * That union store content of event. Event could store pointer to any
 * object, number or time. How to interpret content of that union depends
 * on type of the event.
 */
typedef union zv_event_content_u {
    
    /* Pointer to any object. */
    void *object;

    /* Time after which task would be ready. */
    zv_time_t time;

    /* Unsigned number. */
    uintptr_t unumber;

    /* Signed number. */
    intptr_t number;

} zv_event_content_t;

/**
 * @brief That is event container. Do not modify without API function.
 * 
 * That is event container. Store type of the event and its content.
 * Type could also being empty, which mean that event did not occur.
 */
typedef struct zv_event_s {
    
    /* Type of the event. */
    zv_event_type_t type;

    /* Content of the event. */
    zv_event_content_t content;

} zv_event_t;

/**
 * That would return true, when event is timer in any phrase. Software
 * timers are supported by scheduler, and it is used to determinate which
 * event must being updated by scheduler every task selection loop.
 */
#define __zv_event_is_working_timer(X) (\
    X.type == ZV_EVENT_TIMER_PHRASE_FIRST \
    || X.type == ZV_EVENT_TIMER_PHRASE_SECOND \
)

/** 
 * That return true, when any event occur. It is used to determinate
 * chech if the process should be updated to ZV_TASK_READY state.
 */
#define __zv_event_is_set(X) ( \
    X.type != ZV_EVENT_EMPTY \
    && !__zv_event_is_working_timer(X) \
)

/**
 * That function clean event. After call it, target event would return to
 * default empty state with empty content.
 *
 * @param target Pointer to target event.
 */
static inline void __zv_event_clear(zv_event_t *target) {
    target->type = ZV_EVENT_EMPTY;
    target->content = (zv_event_content_t) { .unumber = 0x00 };
}

/** 
 * @brief That function send event with number.
 *
 * That function would trigger event with number content for choosen task.
 * 
 * @param self Kernel object to work on.
 * @param target Target task TID.
 * @param content Content of event to push.
 * @return True when operation end with success. False when operation
 *         could not being finalized, for example task not exists or 
 *         event already in use.
 */
bool zv_event_push_number(
    struct zv_kernel_s *self,
    zv_tid_t target,
    int64_t content
);

/**
 * @brief That function send event with unsigned number.
 *
 * That function would trigger event with unsigned number content 
 * for choosen task.
 * 
 * @param self Kernel object to work on.
 * @param target Target task TID.
 * @param content Content of event to push.
 * @return True when operation end with success. False when operation
 *         could not being finalized, for example task not exists or 
 *         event already in use.
 */
bool zv_event_push_unumber(
    struct zv_kernel_s *self,
    zv_tid_t target,
    uint64_t content
);

/**
 * @brief That function set software timer for task.
 * 
 * That function would use event to set software timer. It use event 
 * to store timestamp after which time event would be triggered. Timestamp
 * would be calculated automatically by delay time.
 * 
 * @param self Kernel object to work on.
 * @param target Target task TID.
 * @param delay_time Time after which timer event would be triggered 
 *                   is ms. For example 500 for 500ms.
 * @return True when operation end with success. False when operation
 *         could not being finalized, for example task not exists or 
 *         event already in use.
 */
bool zv_event_set_timer(
    struct zv_kernel_s *self,
    zv_tid_t target,
    zv_time_t delay_time
);

/**
 * @brief That function send event with pointer to any data type.
 *
 * That function would trigger event with pointer to object as content.
 * Pointer is void type, which mean that data type must be known by 
 * event receiver.
 * 
 * @param self Kernel object to work on.
 * @param target Target task TID.
 * @param content Pointer to target data.
 * @return True when operation end with success. False when operation
 *         could not being finalized, for example task not exists or 
 *         event already in use.
 */
bool zv_event_push_object(
    struct zv_kernel_s *self,
    zv_tid_t target,
    void *content
);

#endif