Skip to main content
aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
Diffstat (limited to 'runtime/org.eclipse.etrice.runtime.c/src/common/messaging')
-rw-r--r--runtime/org.eclipse.etrice.runtime.c/src/common/messaging/etMessage.h24
-rw-r--r--runtime/org.eclipse.etrice.runtime.c/src/common/messaging/etMessageQueue.c2
-rw-r--r--runtime/org.eclipse.etrice.runtime.c/src/common/messaging/etMessageQueue.h79
-rw-r--r--runtime/org.eclipse.etrice.runtime.c/src/common/messaging/etMessageReceiver.h27
-rw-r--r--runtime/org.eclipse.etrice.runtime.c/src/common/messaging/etMessageService.h125
5 files changed, 227 insertions, 30 deletions
diff --git a/runtime/org.eclipse.etrice.runtime.c/src/common/messaging/etMessage.h b/runtime/org.eclipse.etrice.runtime.c/src/common/messaging/etMessage.h
index 7bba6a1f3..a6c84f26c 100644
--- a/runtime/org.eclipse.etrice.runtime.c/src/common/messaging/etMessage.h
+++ b/runtime/org.eclipse.etrice.runtime.c/src/common/messaging/etMessage.h
@@ -10,17 +10,33 @@
*
*******************************************************************************/
+/**
+ * \file etMessage.h
+ *
+ * the message "base class" that is used for asynchronous messages
+ *
+ * \author Thomas Schuetz
+ */
+
#ifndef _ETMESSAGE_H_
#define _ETMESSAGE_H_
#include "etDatatypes.h"
-typedef struct etMessage{
- struct etMessage* next;
- etInt16 address;
- etInt16 evtID;
+/**
+ * the message structure
+ */
+typedef struct etMessage {
+ struct etMessage* next; /**< pointer to the next message or <code>NULL</code> (single linked list) */
+ etInt16 address; /**< the destination address */
+ etInt16 evtID; /**< the event id */
} etMessage;
+/**
+ * initializes the message fields ("constructor")
+ *
+ * \param self the this pointer
+ */
void etMessage_init(etMessage* self);
#endif /* _ETMESSAGE_H_ */
diff --git a/runtime/org.eclipse.etrice.runtime.c/src/common/messaging/etMessageQueue.c b/runtime/org.eclipse.etrice.runtime.c/src/common/messaging/etMessageQueue.c
index 96a86b046..59dcb5ed4 100644
--- a/runtime/org.eclipse.etrice.runtime.c/src/common/messaging/etMessageQueue.c
+++ b/runtime/org.eclipse.etrice.runtime.c/src/common/messaging/etMessageQueue.c
@@ -58,7 +58,7 @@ etMessage* etMessageQueue_pop(etMessageQueue* self){
self->first = self->last = NULL;
}
else {
- /*more than one message in queue -> set first to nex message*/
+ /*more than one message in queue -> set first to next message*/
self->first = self->first->next;
}
diff --git a/runtime/org.eclipse.etrice.runtime.c/src/common/messaging/etMessageQueue.h b/runtime/org.eclipse.etrice.runtime.c/src/common/messaging/etMessageQueue.h
index e79b57347..3765f39d3 100644
--- a/runtime/org.eclipse.etrice.runtime.c/src/common/messaging/etMessageQueue.h
+++ b/runtime/org.eclipse.etrice.runtime.c/src/common/messaging/etMessageQueue.h
@@ -10,34 +10,103 @@
*
*******************************************************************************/
+/**
+ * \file etMessageQueue.h
+ *
+ * this component implements a message queue (fifo)
+ *
+ * \author Thomas Schuetz
+ */
+
#ifndef _ETMESSAGEQUEUE_H_
#define _ETMESSAGEQUEUE_H_
#include "messaging/etMessage.h"
#include <stddef.h>
+/**
+ * the message queue data structure
+ */
typedef struct etMessageQueue {
- etMessage* first;
- etMessage* last;
- etInt16 highWaterMark;
- etInt16 lowWaterMark;
- etInt16 size;
+ etMessage* first; /**< the head of the list */
+ etMessage* last; /**< the tail of the list */
+ etInt16 highWaterMark; /**< high water mark for statistical purposes */
+ etInt16 lowWaterMark; /**< low water mark for statistical purposes */
+ etInt16 size; /**< the size of the list */
} etMessageQueue;
+/**
+ * initializes the queue data fields ("constructor")
+ *
+ * \param self the this pointer
+ */
void etMessageQueue_init(etMessageQueue* self);
+/**
+ * appends a new message to the queue
+ *
+ * \param self the this pointer
+ */
void etMessageQueue_push(etMessageQueue* self, etMessage* msg);
+/**
+ * removes the first message from the queue
+ *
+ * \param self the this pointer
+ * \return the removed message
+ */
etMessage* etMessageQueue_pop(etMessageQueue* self);
+/**
+ * returns the first message without removing it
+ *
+ * \param self the this pointer
+ * \return the first message without removing it
+ */
etMessage* etMessageQueue_getFirst(etMessageQueue* self);
+/**
+ * returns the last message without removing it
+ *
+ * \param self the this pointer
+ * \return the last message without removing it
+ */
etMessage* etMessageQueue_getLast(etMessageQueue* self);
+/**
+ * returns <code>true</code> if the message queue is not empty
+ *
+ * \param self the this pointer
+ * \return <code>true</code> if the message queue is not empty
+ */
etBool etMessageQueue_isNotEmpty(etMessageQueue* self);
+/**
+ * returns the size of the message queue
+ *
+ * \param self the this pointer
+ * \return the size of the message queue
+ */
etInt16 etMessageQueue_getSize(etMessageQueue* self);
+/**
+ * returns the high water mark of the message queue
+ *
+ * \param self the this pointer
+ * \return the high water mark of the message queue
+ */
etInt16 etMessageQueue_getHighWaterMark(etMessageQueue* self);
+/**
+ * returns the low water mark of the message queue
+ *
+ * \param self the this pointer
+ * \return the low water mark of the message queue
+ */
etInt16 etMessageQueue_getLowWaterMark(etMessageQueue* self);
+/**
+ * resets the low water mark of the message queue to the current
+ * position (size) of the queue
+ *
+ * \param self the this pointer
+ */
void etMessageQueue_resetLowWaterMark(etMessageQueue* self);
diff --git a/runtime/org.eclipse.etrice.runtime.c/src/common/messaging/etMessageReceiver.h b/runtime/org.eclipse.etrice.runtime.c/src/common/messaging/etMessageReceiver.h
index 06cd7df78..566c94707 100644
--- a/runtime/org.eclipse.etrice.runtime.c/src/common/messaging/etMessageReceiver.h
+++ b/runtime/org.eclipse.etrice.runtime.c/src/common/messaging/etMessageReceiver.h
@@ -10,15 +10,40 @@
*
*******************************************************************************/
-
+/**
+ * \file etMessageReceiver.h
+ *
+ * method prototypes used by the messaging
+ *
+ * \author Thomas Schuetz
+ */
#ifndef _ETMESSAGERECEIVER_H_
#define _ETMESSAGERECEIVER_H_
#include "messaging/etMessage.h"
+/**
+ * method prototype that receives a message
+ *
+ * \param self the this pointer
+ * \param ifitem a pointer to the interface item that received the message
+ * \param msg the message
+ */
typedef void (*etActorReceiveMessage)(void* self, const void* ifitem, const etMessage* msg);
+
+/**
+ * method prototype for a dispatcher method
+ *
+ * \param msg the message
+ *
+ * \return <code>true</code> if the message could be delivered
+ */
typedef etBool (*etDispatcherReceiveMessage)(const etMessage* msg);
+
+/**
+ * prototype for the periodic call to the <code>execute()</code> method of the dispatcher
+ */
typedef void (*etDispatcherExecute)(void);
#endif /* _ETMESSAGERECEIVER_H_ */
diff --git a/runtime/org.eclipse.etrice.runtime.c/src/common/messaging/etMessageService.h b/runtime/org.eclipse.etrice.runtime.c/src/common/messaging/etMessageService.h
index a59ed2178..cd729b9a5 100644
--- a/runtime/org.eclipse.etrice.runtime.c/src/common/messaging/etMessageService.h
+++ b/runtime/org.eclipse.etrice.runtime.c/src/common/messaging/etMessageService.h
@@ -10,6 +10,14 @@
*
*******************************************************************************/
+/**
+ * \file etMessageService.h
+ *
+ * this component implements a message service that delivers messages asynchronously
+ *
+ * \author Thomas Schuetz
+ */
+
#ifndef _ETMESSAGESERVICE_H_
#define _ETMESSAGESERVICE_H_
@@ -23,33 +31,54 @@
#include "osal/etSema.h"
#include "osal/etTimer.h"
+/** the address of the message service */
#define MESSAGESERVICE_ADDRESS 1
+/** the base address for other receivers */
#define BASE_ADDRESS 32
+/** enumeration for execution modes */
typedef enum etMessageService_execmode {
- EXECMODE_POLLED, EXECMODE_BLOCKED, EXECMODE_MIXED
+ EXECMODE_POLLED, /**< polled execution for data driven systems */
+ EXECMODE_BLOCKED, /**< blocked execution for asynchronous systems */
+ EXECMODE_MIXED /**< mixed execution for mixed systems */
} etMessageService_execmode;
+/**
+ * the data structure for the message buffer (chunks of equal size)
+ */
typedef struct etBuffer{
- etUInt8 *buffer; /** buffer points to the actual memory position for the message pool */
- etUInt16 maxBlocks; /** number of blocks for the message pool */
- etUInt16 blockSize; /** size of blocks for the message pool */
+ etUInt8 *buffer; /**< buffer points to the actual memory position for the message pool */
+ etUInt16 maxBlocks; /**< number of blocks for the message pool */
+ etUInt16 blockSize; /**< size of blocks for the message pool */
} etBuffer;
typedef struct etMessageService {
- etMessageQueue messageQueue; /** message queue that holds all used messages */
- etMessageQueue messagePool; /** message pool that holds all free messages */
- etBuffer messageBuffer; /** information about the message buffer that holds information about the actual memory position and size for the message pool */
- etDispatcherReceiveMessage msgDispatcher; /** function pointer to the generated message dispatcher function */
- etThread thread; /** thread for the execution of the message service */
- etMutex poolMutex; /** mutex for synchronizing the access to the message pool */
- etMutex queueMutex; /** mutex for synchronizing the access to the message queue */
- etSema executionSemaphore; /** semaphore for waiting and waking up the execution */
- etTimer timer; /** timer for cyclic calls */
- etMessageService_execmode execmode; /** execution mode*/
+ etMessageQueue messageQueue; /**< message queue that holds all used messages */
+ etMessageQueue messagePool; /**< message pool that holds all free messages */
+ etBuffer messageBuffer; /**< information about the message buffer that holds information about
+ the actual memory position and size for the message pool */
+ etDispatcherReceiveMessage msgDispatcher; /**< function pointer to the generated message dispatcher function */
+ etThread thread; /**< thread for the execution of the message service */
+ etMutex poolMutex; /**< mutex for synchronizing the access to the message pool */
+ etMutex queueMutex; /**< mutex for synchronizing the access to the message queue */
+ etSema executionSemaphore; /**< semaphore for waiting and waking up the execution */
+ etTimer timer; /**< timer for cyclic calls */
+ etMessageService_execmode execmode; /**< execution mode*/
} etMessageService;
-/* lifecycle functions to startup, execute and shutdown the message service */
+/**
+ * initialization (construction)
+ *
+ * \param self the this pointer
+ * \param buffer the buffer for the message pool
+ * \param maxBlocks the number of (equal sized) message blocks in the buffer
+ * \param blockSize the size of each message block
+ * \param stackSize the stack size for the thread in which this service will run
+ * \param priority the thread priority
+ * \param interval the polling interval
+ * \param msgDispatcher the dispatcher method
+ * \param execmdoe the execution mode for this message service
+ */
void etMessageService_init(
etMessageService* self,
etUInt8* buffer,
@@ -60,23 +89,81 @@ void etMessageService_init(
etTime interval,
etDispatcherReceiveMessage msgDispatcher,
etMessageService_execmode execmode);
+
+/**
+ * start of the message service (starts the associated thread)
+ *
+ * \param self the this pointer
+ */
void etMessageService_start(etMessageService* self);
+
+/**
+ * the polling method to be called cyclically
+ *
+ * \param self the this pointer
+ */
void etMessageService_execute(etMessageService* self);
+
+/**
+ * stops the message service thread
+ *
+ * \param self the this pointer
+ */
void etMessageService_stop(etMessageService* self);
+
+/**
+ * destroys the message service
+ *
+ * \param self the this pointer
+ */
void etMessageService_destroy(etMessageService* self);
-/* initialization of message pool */
+/**
+ * initialization of message pool
+ *
+ * \param self the this pointer
+ */
void etMessageService_initMessagePool(etMessageService* self);
-/* message queue interface for push and pop messages */
+/**
+ * push a message to the queue. The queue access is synchronized. The method notifies the dispatch thread.
+ *
+ * \param self the this pointer
+ * \msg the message to push
+ */
void etMessageService_pushMessage(etMessageService* self, etMessage* msg);
+
+/**
+ * pop a message from the queue. The queue access is synchronized.
+ *
+ * \param self the this pointer
+ * \return the extracted message
+ */
etMessage* etMessageService_popMessage(etMessageService* self);
-/* message pool interface to get and return (push and pop) messages */
+/**
+ * get a chunk of uninitialized memory interpreted as \ref etMessage from the services memory management
+ *
+ * \param self the this pointer
+ * \param size the size of the message in bytes
+ * \return a message pointer to a chunk of memory with at least the required size
+ */
etMessage* etMessageService_getMessageBuffer(etMessageService* self, etUInt16 size);
+
+/**
+ * return a chunk of previously obtained memory to the message service memory management
+ *
+ * \param self the this pointer
+ * \param buffer the memory to be freed
+ */
void etMessageService_returnMessageBuffer(etMessageService* self, etMessage* buffer);
-/* functions for debug and service information */
+/**
+ * returns the low water mark of the message pool
+ *
+ * \param self the this pointer
+ * \return the low water mark of the message pool
+ */
etInt16 etMessageService_getMessagePoolLowWaterMark(etMessageService* self);

Back to the top