QP/C  5.9.8
qf_ps.c File Reference

Publish-Subscribe services. More...

#include "qf_port.h"
#include "qf_pkg.h"
#include "qassert.h"
#include "qs_port.h"

Go to the source code of this file.

Macros

#define QP_IMPL   /* this is QP implementation */
 

Functions

void QF_psInit (QSubscrList *const subscrSto, enum_t const maxSignal)
 Publish-subscribe initialization. More...
 
void QF_publish_ (QEvt const *const e, void const *const sender)
 Publish event to the framework. More...
 
void QActive_subscribe (QActive const *const me, enum_t const sig)
 Subscribes for delivery of signal sig to the active object me. More...
 
void QActive_unsubscribe (QActive const *const me, enum_t const sig)
 Un-subscribes from the delivery of signal sig to the AO me. More...
 
void QActive_unsubscribeAll (QActive const *const me)
 Un-subscribes from the delivery of all signals to the AO me. More...
 

Variables

QSubscrListQF_subscrList_
 the subscriber list array
 
enum_t QF_maxPubSignal_
 the maximum published signal
 

Detailed Description

Publish-Subscribe services.

Definition in file qf_ps.c.

Function Documentation

◆ QF_psInit()

void QF_psInit ( QSubscrList *const  subscrSto,
enum_t const  maxSignal 
)

Publish-subscribe initialization.

Description
This function initializes the publish-subscribe facilities of QF and must be called exactly once before any subscriptions/publications occur in the application.
Parameters
[in]subscrStopointer to the array of subscriber lists
[in]maxSignalthe dimension of the subscriber array and at the same time the maximum signal that can be published or subscribed.

The array of subscriber-lists is indexed by signals and provides a mapping between the signals and subscriber-lists. The subscriber-lists are bitmasks of type QSubscrList, each bit in the bit mask corresponding to the unique priority of an active object. The size of the QSubscrList bit mask depends on the value of the QF_MAX_ACTIVE macro.

Note
The publish-subscribe facilities are optional, meaning that you might choose not to use publish-subscribe. In that case calling QF_psInit() and using up memory for the subscriber-lists is unnecessary.
See also
QSubscrList
Usage
The following example shows the typical initialization sequence of QF:
int main(void) {
static QEvt const *l_tableQueueSto[N_PHILO];
static QEvt const *l_philoQueueSto[N_PHILO][N_PHILO];
static QSubscrList l_subscrSto[MAX_PUB_SIG];
/* storage for event pools... */
static QF_MPOOL_EL(TableEvt) l_smlPoolSto[2*N_PHILO]; /* small pool */
Philo_ctor(); /* instantiate all Philosopher active objects */
Table_ctor(); /* instantiate the Table active object */
QF_init(); /* initialize the framework and the underlying RT kernel */
BSP_init(); /* initialize the BSP */
/* send object dictionaries for event pools... */
QS_OBJ_DICTIONARY(l_smlPoolSto);
/* init publish-subscribe... */
QF_psInit(l_subscrSto, Q_DIM(l_subscrSto));
/* initialize event pools... */
QF_poolInit(l_smlPoolSto, sizeof(l_smlPoolSto), sizeof(l_smlPoolSto[0]));
/* start the active objects... */
for (n = 0; n < N_PHILO; ++n) {
QACTIVE_START(AO_Philo[n], (uint8_t)(n + 1),
l_philoQueueSto[n], Q_DIM(l_philoQueueSto[n]),
(void *)0, 0U, (QEvt *)0);
}
QACTIVE_START(AO_Table, (uint8_t)(N_PHILO + 1),
l_tableQueueSto, Q_DIM(l_tableQueueSto),
(void *)0, 0U, (QEvt *)0);
return QF_run(); /* run the QF application, QF_run() does not return */
}

Definition at line 85 of file qf_ps.c.

◆ QF_publish_()

void QF_publish_ ( QEvt const *const  e,
void const *const  sender 
)

Publish event to the framework.

Description
This function posts (using the FIFO policy) the event e to all active objects that have subscribed to the signal e->sig, which is called multicasting. The multicasting performed in this function is very efficient based on reference-counting inside the published event ("zero-copy" event multicasting). This function is designed to be callable from any part of the system, including ISRs, device drivers, and active objects.
Note
To avoid any unexpected re-ordering of events posted into AO queues, the event multicasting is performed with scheduler locked. However, the scheduler is locked only up to the priority level of the highest- priority subscriber, so any AOs of even higher priority, which did not subscribe to this event are not affected.
Attention
this function should be called only via the macro QF_PUBLISH()
Precondition
the published signal must be within the configured range

Definition at line 121 of file qf_ps.c.

◆ QActive_subscribe()

void QActive_subscribe ( QActive const *const  me,
enum_t const  sig 
)

Subscribes for delivery of signal sig to the active object me.

Description
This function is part of the Publish-Subscribe event delivery mechanism available in QF. Subscribing to an event means that the framework will start posting all published events with a given signal sig to the event queue of the active object me.
Parameters
[in,out]mepointer (see Object Orientation)
[in]sigevent signal to subscribe
Usage
The following example shows how the Table active object subscribes to three signals in the initial transition:
QState Table_initial(Table * const me, QEvt const * const e) {
(void)e; /* suppress the compiler warning */
QActive_subscribe(&me->super, HUNGRY_SIG); /* subscribe to HUNGRY */
QActive_subscribe(&me->super, DONE_SIG); /*... to DONE */
QActive_subscribe(&me->super, TERMINATE_SIG); /*...and to TERMINATE */
for (n = 0; n < N; ++n) {
me->fork[n] = FREE;
me->isHungry[n] = 0;
}
return Q_TRAN(&Table_serving);
}
See also
QF_publish_(), QActive_unsubscribe(), and QActive_unsubscribeAll()

Definition at line 205 of file qf_ps.c.

◆ QActive_unsubscribe()

void QActive_unsubscribe ( QActive const *const  me,
enum_t const  sig 
)

Un-subscribes from the delivery of signal sig to the AO me.

Description
This function is part of the Publish-Subscribe event delivery mechanism available in QF. Un-subscribing from an event means that the framework will stop posting published events with a given signal sig to the event queue of the active object me.
Parameters
[in]mepointer (see Object Orientation)
[in]sigevent signal to unsubscribe
Note
Due to the latency of event queues, an active object should NOT assume that a given signal sig will never be dispatched to the state machine of the active object after un-subscribing from that signal. The event might be already in the queue, or just about to be posted and the un-subscribe operation will not flush such events.
Un-subscribing from a signal that has never been subscribed in the first place is considered an error and QF will raise an assertion.
See also
QF_publish_(), QActive_subscribe(), and QActive_unsubscribeAll()
Precondition
the singal and the prioriy must be in ragne, the AO must also be registered with the framework

Definition at line 250 of file qf_ps.c.

◆ QActive_unsubscribeAll()

void QActive_unsubscribeAll ( QActive const *const  me)

Un-subscribes from the delivery of all signals to the AO me.

Description
This function is part of the Publish-Subscribe event delivery mechanism available in QF. Un-subscribing from all events means that the framework will stop posting any published events to the event queue of the active object me.
Parameters
[in]mepointer (see Object Orientation)
Note
Due to the latency of event queues, an active object should NOT assume that no events will ever be dispatched to the state machine of the active object after un-subscribing from all events. The events might be already in the queue, or just about to be posted and the un-subscribe operation will not flush such events. Also, the alternative event-delivery mechanisms, such as direct event posting or time events, can be still delivered to the event queue of the active object.
See also
QF_publish_(), QActive_subscribe(), and QActive_unsubscribe()

Definition at line 297 of file qf_ps.c.