3. The main() Function

This QP/C++ Tutorial is adapted from Chapter 1 of Practical UML Statecharts in C/C++, Second Edition
by Miro Samek, the founder and president of Quantum Leaps, LLC.

Prev: 2. Let's Play
Next: 4. Designing an Event-Driven Application

Perhaps the best place to start the explanation of the "Fly 'n' Shoot" application code is the main() function, located in the file main.cpp. Unless indicated otherwise in this Tutorial, you can browse the code either in the DOS version, or the ARM-Cortex version, because the application source code is identical in both. The complete main.cpp file is shown in Listing 3-1.

Note:: To explain code listings, I place numbers in parentheses at the interesting lines in the left margin of the listing. I then use these labels in the left margin of the explanation section that immediately follows the listing. Occasionally, to unambiguously refer to a line of a particular listing from sections of text other than the explanation section, I use the full reference consisting of the listing number followed by the label. For example, Listing 3-1(18) refers to the label (18) in Listing 3-1

Listing 3-1 The file main.cpp of the "Fly 'n' Shoot" game application.

 (1) #include "qp_port.h"
 (2) #include "bsp.h"
 (3) #include "game.h"

     // Local-scope objects -------------------------------------------------------
 (4) static QEvent const * l_missileQueueSto[2];
 (5) static QEvent const * l_shipQueueSto[3];
 (6) static QEvent const * l_tunnelQueueSto[GAME_MINES_MAX + 5];
 (7) static ObjectPosEvt   l_smlPoolSto[GAME_MINES_MAX + 5];    // small event pool
 (8) static ObjectImageEvt l_medPoolSto[GAME_MINES_MAX + 5];   // medium event pool
 (9) static QSubscrList    l_subscrSto[MAX_PUB_SIG];

     //............................................................................
     void main(int argc, char *argv[]) {

(10)     BSP_init(argc, argv);              // initialize the Board Support Package

(11)     QF::init();       // initialize the framework and the underlying RT kernel

                                                   // initialize the event pools...
(12)     QF::poolInit(l_smlPoolSto, sizeof(l_smlPoolSto), sizeof(l_smlPoolSto[0]));
(13)     QF::poolInit(l_medPoolSto, sizeof(l_medPoolSto), sizeof(l_medPoolSto[0]));

(14)     QF::psInit(l_subscrSto, Q_DIM(l_subscrSto));     // init publish-subscribe

                                                     // start the active objects...
(15)     AO_Missile->start(1,                                           // priority
                           l_missileQueueSto, Q_DIM(l_missileQueueSto),// evt queue
                           (void *)0, 0,                     // no per-thread stack
                           (QEvent *)0);                 // no initialization event
(16)     AO_Ship   ->start(2,                                           // priority
                           l_shipQueueSto, Q_DIM(l_shipQueueSto),      // evt queue
                           (void *)0, 0,                     // no per-thread stack
                           (QEvent *)0);                 // no initialization event
(17)     AO_Tunnel ->start(3,                                           // priority
                           l_tunnelQueueSto, Q_DIM(l_tunnelQueueSto),  // evt queue
                           (void *)0, 0,                     // no per-thread stack
                           (QEvent *)0);                 // no initialization event

(18)     QF::run();                                       // run the QF application
     }

(1) The "Fly 'n' Shoot" game is an example of an application implemented with the QP event-driven platform. Every application C-file that uses QP must include the qp_port.h header file. This header file contains the specific adaptation of QP to the given processor, operating system, and compiler, which is called a port. Each QP port is located in a separate directory and the C compiler finds the right qp_port.h header file through the include search path provided to the compiler (typically via the -I compiler option). That way I don't need to change the application source code to recompile it for a different processor or compiler. I only need to instruct the compiler to look in a different QP port directory for the qp_port.h header file. For example, the DOS version includes the qp_port.h header file from the directory <qpcpp>\ports\80x86\dos\watcom\l\, and the ARM-Cortex version from the directory <qpcpp>\ports\arm-cortex\vanilla\iar\.

(2) The bsp.h header file contains the interface to the Board Support Package and is located in the application directory.

(3) The game.h header file contains the declarations of events and other facilities shared among the components of the application. I will discuss this header file in the upcoming Section 6. Defining Event Signals and Event Parameters. This header file is located in the application directory.

The QP event-driven platform is a collection of components, such as the QEP event processor that executes state machines according to the UML semantics and the QF real-time framework that implements the active object computing model. Active objects in QF are encapsulated state machines (each with an event queue, a separate task context, and a unique priority) that communicate with one another asynchronously by sending and receiving events, while QF handles all the details of thread-safe event exchange and queuing. Within an active object, the events are processed by the QEP event processor sequentially in a run-to-completion (RTC) fashion, meaning that processing of one event must necessarily complete before processing the next event.

(4-6) The application must provide storage for the event queues of all active objects used in the application. Here the storage is provided at compile time through the statically allocated arrays of immutable (const) pointers to events, because QF event queues hold just pointers to events, not events themselves. Events are represented as instances of the QEvent structure declared in the qp_port.h header file. Each event queue of an active object can have a different size and you need to decide this size based on your knowledge of the application. I discuss the event queues in Chapters 6 and 7 of Practical UML Statecharts in C/C++, Second Edition.

(7-8) The application must also provide storage for event pools that the framework uses for fast and deterministic dynamic allocation of events. Each event pool manages can provide only fixed-size memory blocks. To avoid wasting memory by using oversized blocks for small events, the QF framework can manage up to three event pools of different block sizes (for small, medium, and large events). The "Fly 'n' Shoot" application uses only two out of the three possible event pools (the small and medium pools).

The QF real-time framework supports two event delivery mechanisms: the simple direct event posting to active objects, and the more advanced mechanism called publish-subscribe that decouples event producers from the consumers. In the publish-subscribe mechanism, active objects subscribe to events by the framework. Event producers publish the events to the framework. Upon each publication request, the framework delivers the event to all active objects that had subscribed to that event type. One obvious implication of publish-subscribe is that the framework must store the subscriber information, whereas it must be possible to handle multiple subscribers to any give event type. The event delivery mechanisms are described in Chapters 6 and 7 of Practical UML Statecharts in C/C++, Second Edition.

(9) The "Fly 'n' Shoot" application uses the publish-subscribe event delivery mechanism supported by QF, so it needs to provide the storage for the subscriber lists. The subscriber lists remembers which active objects have subscribed to which events. The size of the subscriber database depends on both the number of published events, which is specified in the MAX_PUB_SIG constant found in the game.h header file, and the maximum number of active objects allowed in the system, which is determined by the QF configuration parameter QF_MAX_ACTIVE.

(10) The function BSP_init() initializes the board and is defined in the bsp.cpp file.

(11) The function QF::init() initializes the QF component and the underlying RTOS/kernel, if such software is used. You need to call QF::init() before you invoke any of QF services.

(12-13) The function QF::poolInit() initializes the event pools. The parameters of this function are the pointer to the event pool storage, the size of this storage, and the block-size of this pool. You can call this function up to three times to initialize up to three event pools. The subsequent calls to QF::poolInit() must be made in the increasing order of block sizes. For instance, the small block-size pool must be initialized before the medium block-size pool.

(14) The function QF::poolInit() initializes the publish-subscribe event delivery mechanism of QF. The parameters of this function are the pointer to the subscriber-list array and the dimension of this array.

The utility macro Q_DIM(a) provides the dimension of a one-dimensional array a[] computed as sizeof(a)/sizeof(a[0]), which is a compile-time constant. The use of this macro simplifies the code because it allows me to eliminate many define constants that otherwise I would need to provide for the dimensions of various arrays. I can simply hard-code the dimension right in the definition of an array, which is the only place that I specify it. I then use the macro Q_DIM() whenever I need this dimension in the code.

(15-17) The function QActive::start() tells the QF framework to start managing an active object as part of the application. The function takes the following parameters: the pointer to the active object structure, the priority of the active object, the pointer to its event queue, the dimension (length) of that queue, and three other parameters that I explain in Chapter 7 of Practical UML Statecharts in C/C++, Second Edition, since they are not relevant at this point. The active object priorities in QF are numbered from 1 to QF_MAX_ACTIVE, inclusive, where a higher priority number denotes higher urgency of the active object. The constant QF_MAX_ACTIVE is defined in the QF port header file qf_port.h and currently cannot exceed 63.

I like to keep the code and data of every active object strictly encapsulated within its own C-file. For example, all code and data for the active object Ship are encapsulated in the file ship.cpp, with the external interface consisting of the pointer AO_Ship.

(18) At this point, you have provided to the framework all the storage and information it needs to manage your application. The last thing you must do is to call the function QF::run() to pass the control to the framework.

After the call to QF::run() the framework is in full control. The framework executes the application by calling your code, not the other way around. The function QF::run() never returns the control back to main(). In the DOS version of the "Fly 'n' Shoot" game, you can terminate the application by pressing the ESC key, in which case QF::run() exits to DOS, but not to main(). In an embedded system, such as the ARM-Cortex board, QF::run() runs forever or till the power is removed, whichever comes first.

Note:: For best cross-platform portability, the source code uses consistently the UNIX end-of-line convention (lines are terminated with LF only, 0xA character). This convention seems to be working for all C/C++ compilers and cross-compilers, including legacy DOS-era tools. In contrast, the DOS/Windows end-of-line convention (lines terminated with the CR,LF, or 0xD,0xA pair of characters), is known to cause problems on UNIX-like platforms, especially in the multi-line preprocessor macros.

Prev: 2. Let's Play
Next: 4. Designing an Event-Driven Application