David Smart / CANQueue2

CAN Queue mechanism permitting creation and management of CAN messages through a queueing

CANQueue.h@0:7cf23260330d, 2012-07-15 (annotated)

Committer:
WiredHome
Date:
Sun Jul 15 15:15:20 2012 +0000
Revision:
0:7cf23260330d
[mbed] converted /A_CANAdapter/CANUtilities/CANQueue

Who changed what in which revision?

UserRevisionLine numberNew contents of line
WiredHome 0:7cf23260330d 1 /// @file CANQueue.h
WiredHome 0:7cf23260330d 2 /// The CAN Queue mechanism permits the creation and management of
WiredHome 0:7cf23260330d 3 /// messages through a CAN queue.
WiredHome 0:7cf23260330d 4 ///
WiredHome 0:7cf23260330d 5 /// @version 1.02
WiredHome 0:7cf23260330d 6 ///
WiredHome 0:7cf23260330d 7 /// @note Copyright &copr; 2011 by Smartware Computing, all rights reserved.
WiredHome 0:7cf23260330d 8 /// Individuals may use this application for evaluation or non-commercial
WiredHome 0:7cf23260330d 9 /// purposes. Within this restriction, changes may be made to this application
WiredHome 0:7cf23260330d 10 /// as long as this copyright notice is retained. The user shall make
WiredHome 0:7cf23260330d 11 /// clear that their work is a derived work, and not the original.
WiredHome 0:7cf23260330d 12 /// Users of this application and sources accept this application "as is" and
WiredHome 0:7cf23260330d 13 /// shall hold harmless Smartware Computing, for any undesired results while
WiredHome 0:7cf23260330d 14 /// using this application - whether real or imagined.
WiredHome 0:7cf23260330d 15 ///
WiredHome 0:7cf23260330d 16 /// @author David Smart, Smartware Computing
WiredHome 0:7cf23260330d 17 ///
WiredHome 0:7cf23260330d 18 /// v1.02 - 20111030
WiredHome 0:7cf23260330d 19 /// \li Added QueueSize api to retrieve the defined size
WiredHome 0:7cf23260330d 20 /// v1.01 - 29 May 2011
WiredHome 0:7cf23260330d 21 /// \li Added QueueMax to find the highest water mark
WiredHome 0:7cf23260330d 22 /// \li Added delete in the destructor
WiredHome 0:7cf23260330d 23 /// \li Added [global] interrupt disable around the critical sections
WiredHome 0:7cf23260330d 24 /// v1.00 - no date
WiredHome 0:7cf23260330d 25 /// \li original version
WiredHome 0:7cf23260330d 26
WiredHome 0:7cf23260330d 27 #ifndef CANQUEUE_H
WiredHome 0:7cf23260330d 28 #define CANQUEUE_H
WiredHome 0:7cf23260330d 29 #include "CANMessage.h"
WiredHome 0:7cf23260330d 30
WiredHome 0:7cf23260330d 31 /// This is a simple queue mechanism for CANmsg messages
WiredHome 0:7cf23260330d 32 ///
WiredHome 0:7cf23260330d 33 /// CANQueue is a circular queue that is designed for CAN messages.
WiredHome 0:7cf23260330d 34 /// It can be used, for example, between a CAN receive interrupt
WiredHome 0:7cf23260330d 35 /// and a background process to offload those received messages.
WiredHome 0:7cf23260330d 36 /// In this way, the receive interrupt is light weight.
WiredHome 0:7cf23260330d 37 ///
WiredHome 0:7cf23260330d 38 class CANQueue
WiredHome 0:7cf23260330d 39 {
WiredHome 0:7cf23260330d 40 public:
WiredHome 0:7cf23260330d 41 /// CANQueue constructor, which sets the queue size
WiredHome 0:7cf23260330d 42 ///
WiredHome 0:7cf23260330d 43 /// This sets the queue size and initializes the data elements
WiredHome 0:7cf23260330d 44 ///
WiredHome 0:7cf23260330d 45 /// @param Size is the size in entries for this queue
WiredHome 0:7cf23260330d 46 ///
WiredHome 0:7cf23260330d 47 CANQueue(int Size = 3);
WiredHome 0:7cf23260330d 48
WiredHome 0:7cf23260330d 49 /// CANQueue destructor
WiredHome 0:7cf23260330d 50 ///
WiredHome 0:7cf23260330d 51 /// This destroys the queue
WiredHome 0:7cf23260330d 52 ///
WiredHome 0:7cf23260330d 53 ~CANQueue();
WiredHome 0:7cf23260330d 54
WiredHome 0:7cf23260330d 55 /// Enqueue a new message into the queue
WiredHome 0:7cf23260330d 56 ///
WiredHome 0:7cf23260330d 57 /// If we enqueue until we overwrite the dequeue location, then
WiredHome 0:7cf23260330d 58 /// we have lost the oldest message and must force the dequeue
WiredHome 0:7cf23260330d 59 /// forward by one position.
WiredHome 0:7cf23260330d 60 ///
WiredHome 0:7cf23260330d 61 /// @param msg is the message to be enqueued
WiredHome 0:7cf23260330d 62 /// @return true if no overwrite of the oldest message
WiredHome 0:7cf23260330d 63 /// @return false if the oldest message was overwritten
WiredHome 0:7cf23260330d 64 ///
WiredHome 0:7cf23260330d 65 bool Enqueue(CANmsg msg);
WiredHome 0:7cf23260330d 66
WiredHome 0:7cf23260330d 67 /// Enqueue a new message into the queue
WiredHome 0:7cf23260330d 68 ///
WiredHome 0:7cf23260330d 69 /// If we enqueue until we overwrite the dequeue location, then
WiredHome 0:7cf23260330d 70 /// we have lost the oldest message and must force the dequeue
WiredHome 0:7cf23260330d 71 /// forward by one position.
WiredHome 0:7cf23260330d 72 ///
WiredHome 0:7cf23260330d 73 /// @param msg is the message to be enqueued
WiredHome 0:7cf23260330d 74 /// @return true if no overwrite of the oldest message
WiredHome 0:7cf23260330d 75 /// @return false if the oldest message was overwritten
WiredHome 0:7cf23260330d 76 ///
WiredHome 0:7cf23260330d 77 bool Enqueue(CANmsg *msg);
WiredHome 0:7cf23260330d 78
WiredHome 0:7cf23260330d 79 /// Dequeue a message from the queue
WiredHome 0:7cf23260330d 80 ///
WiredHome 0:7cf23260330d 81 /// If there is a message we'll copy it out to the callers message
WiredHome 0:7cf23260330d 82 /// to which they provided the handle.
WiredHome 0:7cf23260330d 83 ///
WiredHome 0:7cf23260330d 84 /// @param msg is a pointer to the callers memory to copy the message into
WiredHome 0:7cf23260330d 85 /// @returns true if a message was dequeued
WiredHome 0:7cf23260330d 86 /// @returns false if the queue was empty
WiredHome 0:7cf23260330d 87 ///
WiredHome 0:7cf23260330d 88 bool Dequeue(CANmsg *msg);
WiredHome 0:7cf23260330d 89
WiredHome 0:7cf23260330d 90 /// Gets the count of the number of items in the queue
WiredHome 0:7cf23260330d 91 ///
WiredHome 0:7cf23260330d 92 /// @returns number of queue entries
WiredHome 0:7cf23260330d 93 ///
WiredHome 0:7cf23260330d 94 int QueueCount() { return queueCount; }
WiredHome 0:7cf23260330d 95
WiredHome 0:7cf23260330d 96 /// Get the maximum number of items that were ever in the queue
WiredHome 0:7cf23260330d 97 ///
WiredHome 0:7cf23260330d 98 /// @returns maximum as the high water mark
WiredHome 0:7cf23260330d 99 ///
WiredHome 0:7cf23260330d 100 int QueueMax() { return queueMaxCount; }
WiredHome 0:7cf23260330d 101
WiredHome 0:7cf23260330d 102 /// Get the defined queue size
WiredHome 0:7cf23260330d 103 ///
WiredHome 0:7cf23260330d 104 /// @returns size of the queue as defined
WiredHome 0:7cf23260330d 105 ///
WiredHome 0:7cf23260330d 106 int QueueSize() { return queueSize; }
WiredHome 0:7cf23260330d 107
WiredHome 0:7cf23260330d 108 private:
WiredHome 0:7cf23260330d 109 CANmsg * queue; ///<!- the queue
WiredHome 0:7cf23260330d 110 int queueSize; ///<!- the size of the queue in entries
WiredHome 0:7cf23260330d 111 int queueCount; ///<!- the current number of items in the queue
WiredHome 0:7cf23260330d 112 int queueMaxCount; ///<!- the maximum ever held in the queue
WiredHome 0:7cf23260330d 113 int enqueuePosition; ///<!- where the next item will be enqueued
WiredHome 0:7cf23260330d 114 int dequeuePosition; ///<!- where the next item will be dequeued
WiredHome 0:7cf23260330d 115 };
WiredHome 0:7cf23260330d 116
WiredHome 0:7cf23260330d 117 #endif // CANQUEUE_H