tn_eventgrp.h

Go to the documentation of this file.

/*******************************************************************************
 *
 * TNeoKernel: real-time kernel initially based on TNKernel
 *
 *    TNKernel:                  copyright © 2004, 2013 Yuri Tiomkin.
 *    PIC32-specific routines:   copyright © 2013, 2014 Anders Montonen.
 *    TNeoKernel:                copyright © 2014       Dmitry Frank.
 *
 *    TNeoKernel was born as a thorough review and re-implementation of
 *    TNKernel. The new kernel has well-formed code, inherited bugs are fixed
 *    as well as new features being added, and it is tested carefully with
 *    unit-tests.
 *
 *    API is changed somewhat, so it's not 100% compatible with TNKernel,
 *    hence the new name: TNeoKernel.
 *
 *    Permission to use, copy, modify, and distribute this software in source
 *    and binary forms and its documentation for any purpose and without fee
 *    is hereby granted, provided that the above copyright notice appear
 *    in all copies and that both that copyright notice and this permission
 *    notice appear in supporting documentation.
 *
 *    THIS SOFTWARE IS PROVIDED BY THE DMITRY FRANK AND CONTRIBUTORS "AS IS"
 *    AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 *    IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 *    PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL DMITRY FRANK OR CONTRIBUTORS BE
 *    LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 *    CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 *    SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 *    INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 *    CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 *    ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
 *    THE POSSIBILITY OF SUCH DAMAGE.
 *
 ******************************************************************************/

/**
 * \file
 *
 * Event group.
 *
 * An event group has an internal variable (of type `TN_UWord`), which is
 * interpreted as a bit pattern where each bit represents an event. An event
 * group also has a wait queue for the tasks waiting on these events. A task
 * may set specified bits when an event occurs and may clear specified bits
 * when necessary. 
 *
 * The tasks waiting for an event(s) are placed in the event group's wait
 * queue. An event group is a very suitable synchronization object for cases
 * where (for some reasons) one task has to wait for many tasks, or vice versa,
 * many tasks have to wait for one task.
 *
 * \section eventgrp_connect Connecting an event group to other system objects
 *
 * Sometimes task needs to wait for different system events, the most common
 * examples are:
 *
 * - wait for a message from the queue(s) plus wait for some
 *   application-dependent event;
 * - wait for messages from multiple queues.
 *
 * If the kernel doesn't offer a mechanism for that, programmer usually have to
 * use polling services on these queues and sleep for a few system ticks.
 * Obviously, this approach has serious drawbacks: we have a lot of useless
 * context switches, and response for the message gets much slower. Actually,
 * we lost the main goal of the preemtive kernel when we use polling services
 * like that.
 *
 * TNeoKernel offers a solution: an event group can be connected to other
 * kernel objects, and these objects will maintain certain flags inside that
 * event group automatically.
 *
 * So, in case of multiple queues, we can act as follows (assume we have two
 * queues: Q1 and Q2) :
 * 
 * - create event group EG;
 * - connect EG with flag 1 to Q1;
 * - connect EG with flag 2 to Q2;
 * - when task needs to receive a message from either Q1 or Q2, it just waits
 *   for the any of flags 1 or 2 in the EG, this is done in the single call 
 *   to `tn_eventgrp_wait()`.
 * - when that event happened, task checks which flag is set, and receive
 *   message from the appropriate queue.
 *
 * Please note that task waiting for the event should **not** clear the flag
 * manually: this flag is maintained completely by the queue. If the queue is
 * non-empty, the flag is set. If the queue becomes empty, the flag is cleared.
 * 
 * For the information on system services related to queue, refer to the \ref 
 * tn_dqueue.h "queue reference".
 *
 * There is an example project available that demonstrates event group
 * connection technique: `examples/queue_eventgrp_conn`. Be sure to examine the
 * readme there.
 *
 */

#ifndef _TN_EVENTGRP_H
#define _TN_EVENTGRP_H

/*******************************************************************************
 *    INCLUDED FILES
 ******************************************************************************/

#include "tn_list.h"
#include "tn_common.h"
#include "tn_sys.h"



#ifdef __cplusplus
extern "C"  {     /*}*/
#endif

/*******************************************************************************
 *    PUBLIC TYPES
 ******************************************************************************/

/**
 * Events waiting mode: wait for all flags to be set or just for any of the 
 * specified flags to be set.
 */
enum TN_EGrpWaitMode {
   ///
   /// Task waits for **any** of the event bits from the `wait_pattern` 
   /// to be set in the event group
   TN_EVENTGRP_WMODE_OR     = (1 << 0),
   ///
   /// Task waits for **all** of the event bits from the `wait_pattern` 
   /// to be set in the event group
   TN_EVENTGRP_WMODE_AND    = (1 << 1),
};

/**
 * Modify operation: set, clear or toggle. To be used in `tn_eventgrp_modify()`
 * / `tn_eventgrp_imodify()` functions.
 */
enum TN_EGrpOp {
   ///
   /// Set flags that are set in given `pattern` argument. Note that this
   /// operation can lead to the context switch, since other high-priority 
   /// task(s) might wait for the event.
   TN_EVENTGRP_OP_SET,
   ///
   /// Clear flags that are set in the given `pattern` argument.
   /// This operation can **not** lead to the context switch, 
   /// since tasks can't wait for events to be cleared.
   TN_EVENTGRP_OP_CLEAR,
   /// Toggle flags that are set in the given `pattern` argument. Note that this
   /// operation can lead to the context switch, since other high-priority 
   /// task(s) might wait for the event that was just set (if any).
   TN_EVENTGRP_OP_TOGGLE,
};

/**
 * Event group
 */
struct TN_EventGrp {
   struct TN_ListItem   wait_queue; //!< task wait queue
   TN_UWord             pattern;    //!< current flags pattern
   enum TN_ObjId        id_event;   //!< id for object validity verification
};

/**
 * EventGrp-specific fields related to waiting task,
 * to be included in struct TN_Task.
 */
struct TN_EGrpTaskWait {
   ///
   /// event wait pattern 
   TN_UWord wait_pattern;
   ///
   /// event wait mode: `AND` or `OR`
   enum TN_EGrpWaitMode wait_mode;
   ///
   /// pattern that caused task to finish waiting
   TN_UWord actual_pattern;
};

/**
 * A link to event group: used when event group can be connected to 
 * some kernel object, such as queue.
 */
struct TN_EGrpLink {
   ///
   /// event group whose event(s) should be managed by other kernel object
   struct TN_EventGrp *eventgrp;
   ///
   /// event pattern to manage
   TN_UWord pattern;
};


/*******************************************************************************
 *    GLOBAL VARIABLES
 ******************************************************************************/

/*******************************************************************************
 *    DEFINITIONS
 ******************************************************************************/



/*******************************************************************************
 *    PUBLIC FUNCTION PROTOTYPES
 ******************************************************************************/

/**
 * Construct event group. `id_event` field should not contain `#TN_ID_EVENTGRP`,
 * otherwise, `#TN_RC_WPARAM` is returned.
 *
 * $(TN_CALL_FROM_TASK)
 * $(TN_CALL_FROM_ISR)
 * $(TN_LEGEND_LINK)
 *
 * @param eventgrp
 *    Pointer to already allocated struct TN_EventGrp
 * @param initial_pattern
 *    Initial events pattern.
 *
 * @return 
 *    * `#TN_RC_OK` if event group was successfully created;
 *    * If `#TN_CHECK_PARAM` is non-zero, additional return code
 *      is available: `#TN_RC_WPARAM`.
 */
enum TN_RCode tn_eventgrp_create(
      struct TN_EventGrp  *eventgrp,
      TN_UWord             initial_pattern
      );

/**
 * Destruct event group.
 * 
 * All tasks that wait for the event(s) become runnable with `#TN_RC_DELETED`
 * code returned.
 *
 * $(TN_CALL_FROM_TASK)
 * $(TN_CAN_SWITCH_CONTEXT)
 * $(TN_LEGEND_LINK)
 *
 * @param eventgrp   Pointer to event groupt to be deleted.
 *
 * @return 
 *    * `#TN_RC_OK` if event group was successfully deleted;
 *    * `#TN_RC_WCONTEXT` if called from wrong context;
 *    * If `#TN_CHECK_PARAM` is non-zero, additional return codes
 *      are available: `#TN_RC_WPARAM` and `#TN_RC_INVALID_OBJ`.
 */
enum TN_RCode tn_eventgrp_delete(struct TN_EventGrp *eventgrp);

/**
 * Wait for specified event(s) in the event group. If the specified event
 * is already active, function returns `#TN_RC_OK` immediately. Otherwise,
 * behavior depends on `timeout` value: refer to `#TN_Timeout`.
 *
 * $(TN_CALL_FROM_TASK)
 * $(TN_CAN_SWITCH_CONTEXT)
 * $(TN_CAN_SLEEP)
 * $(TN_LEGEND_LINK)
 *
 * @param eventgrp
 *    Pointer to event group to wait events from
 * @param wait_pattern
 *    Events bit pattern for which task should wait
 * @param wait_mode
 *    Specifies whether task should wait for **all** the event bits from
 *    `wait_pattern` to be set, or for just **any** of them 
 *    (see enum `#TN_EGrpWaitMode`)
 * @param p_flags_pattern
 *    Pointer to the `TN_UWord` variable in which actual event pattern
 *    that caused task to stop waiting will be stored.
 *    May be `NULL`.
 * @param timeout
 *    refer to `#TN_Timeout`
 *
 * @return
 *    * `#TN_RC_OK` if specified event is active (so the task can check 
 *      variable pointed to by `p_flags_pattern` if it wasn't `NULL`).
 *    * `#TN_RC_WCONTEXT` if called from wrong context;
 *    * Other possible return codes depend on `timeout` value,
 *      refer to `#TN_Timeout`
 *    * If `#TN_CHECK_PARAM` is non-zero, additional return codes
 *      are available: `#TN_RC_WPARAM` and `#TN_RC_INVALID_OBJ`.
 */
enum TN_RCode tn_eventgrp_wait(
      struct TN_EventGrp  *eventgrp,
      TN_UWord             wait_pattern,
      enum TN_EGrpWaitMode wait_mode,
      TN_UWord            *p_flags_pattern,
      TN_Timeout           timeout
      );

/**
 * The same as `tn_eventgrp_wait()` with zero timeout.
 *
 * $(TN_CALL_FROM_TASK)
 * $(TN_CAN_SWITCH_CONTEXT)
 * $(TN_LEGEND_LINK)
 */
enum TN_RCode tn_eventgrp_wait_polling(
      struct TN_EventGrp  *eventgrp,
      TN_UWord             wait_pattern,
      enum TN_EGrpWaitMode wait_mode,
      TN_UWord            *p_flags_pattern
      );

/**
 * The same as `tn_eventgrp_wait()` with zero timeout, but for using in the ISR.
 *
 * $(TN_CALL_FROM_ISR)
 * $(TN_CAN_SWITCH_CONTEXT)
 * $(TN_LEGEND_LINK)
 */
enum TN_RCode tn_eventgrp_iwait_polling(
      struct TN_EventGrp  *eventgrp,
      TN_UWord             wait_pattern,
      enum TN_EGrpWaitMode wait_mode,
      TN_UWord            *p_flags_pattern
      );

/**
 * Modify current events bit pattern in the event group. Behavior depends
 * on the given `operation`: refer to `enum #TN_EGrpOp`
 *
 * $(TN_CALL_FROM_TASK)
 * $(TN_CAN_SWITCH_CONTEXT)
 * $(TN_LEGEND_LINK)
 *
 * @param eventgrp
 *    Pointer to event group to modify events in
 * @param operation
 *    Actual operation to perform: set, clear or toggle.
 *    Refer to `enum #TN_EGrpOp`
 * @param pattern
 *    Events pattern to be applied (depending on `operation` value)
 *
 * @return
 *    * `#TN_RC_OK` on success;
 *    * `#TN_RC_WCONTEXT` if called from wrong context;
 *    * If `#TN_CHECK_PARAM` is non-zero, additional return codes
 *      are available: `#TN_RC_WPARAM` and `#TN_RC_INVALID_OBJ`.
 */
enum TN_RCode tn_eventgrp_modify(
      struct TN_EventGrp  *eventgrp,
      enum TN_EGrpOp       operation,
      TN_UWord             pattern
      );

/**
 * The same as `tn_eventgrp_modify()`, but for using in the ISR.
 *
 * $(TN_CALL_FROM_ISR)
 * $(TN_CAN_SWITCH_CONTEXT)
 * $(TN_LEGEND_LINK)
 */
enum TN_RCode tn_eventgrp_imodify(
      struct TN_EventGrp  *eventgrp,
      enum TN_EGrpOp       operation,
      TN_UWord             pattern
      );


#ifdef __cplusplus
}  /* extern "C" */
#endif

#endif // _TN_EVENTGRP_H

/*******************************************************************************
 *    end of file
 ******************************************************************************/