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.c. 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.c 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(21) refers to the label (21) in Listing 3-1

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

 (1) #include "qp_port.h"                                         /* the QP port */
 (2) #include "bsp.h"                                   /* Board Support Package */
 (3) #include "game.h"                                       /* this application */

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

     /*..........................................................................*/
     void main(int argc, char *argv[]) {
                               /* explicitly invoke the active objects' ctors... */
(10)     Missile_ctor();
(11)     Ship_ctor();
(12)     Tunnel_ctor();

(13)     BSP_init(argc, argv);           /* initialize the Board Support Package */
(14)     QF_init();     /* initialize the framework and the underlying RT kernel */

                                                /* initialize the event pools... */
(15)     QF_poolInit(l_smlPoolSto, sizeof(l_smlPoolSto), sizeof(l_smlPoolSto[0]));
(16)     QF_poolInit(l_medPoolSto, sizeof(l_medPoolSto), sizeof(l_medPoolSto[0]));

(17)     QF_psInit(l_subscrSto, Q_DIM(l_subscrSto));   /* init publish-subscribe */

                                                  /* start the active objects... */
(18)     QActive_start(AO_Missile,/* global pointer to the Missile active object */
                       1,                                   /* priority (lowest) */
                       l_missileQueueSto, Q_DIM(l_missileQueueSto), /* evt queue */
                       (void *)0, 0,                      /* no per-thread stack */
                       (QEvent *)0);                  /* no initialization event */
(19)     QActive_start(AO_Ship,      /* global pointer to the Ship active object */
                       2,                                            /* priority */
                       l_shipQueueSto,    Q_DIM(l_shipQueueSto),    /* evt queue */
                       (void *)0, 0,                      /* no per-thread stack */
                       (QEvent *)0);                  /* no initialization event */
(20)     QActive_start(AO_Tunnel,  /* global pointer to the Tunnel active object */
                       3,                                            /* priority */
                       l_tunnelQueueSto,  Q_DIM(l_tunnelQueueSto),  /* evt queue */
                       (void *)0, 0,                      /* no per-thread stack */
                       (QEvent *)0);                  /* no initialization event */

(21)     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 <qpc>\ports\80x86\dos\watcom\l\, and the ARM-Cortex version from the directory <qpc>\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-12) These functions perform an early initialization of the active objects in the system. They play the role of static "constructors", which in C you need to invoke explicitly. (C++ calls such static constructors implicitly before entering main()).

(13) The function BSP_init() initializes the board and is defined in the bsp.c file.

(14) 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.

(15-16) 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.

(17) 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.

(18-20) 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.c, with the external interface consisting of the function Ship_ctor() and the pointer AO_Ship.

(21) 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