詳細説明

これは、キューの型event 、EventQueueOverrunPolicy 、および最大size を必要とするテンプレートクラスである。デフォルトはEventQueueOverrunPolicy_Discard で、キューのサイズは5 です。詳細はAdjusting the Queue Size を参照してください。

一般に、割り込みコンテキストでないときにpostEvent 関数を使用するか、割り込みハンドラからpostEventFromInterrupt 関数を使用して、イベントをキューにポストすることができます。onEvent をオーバーライドして、通常は次のフレームでイベントを処理します。

DoubleQueue はベアメタルプラットフォームのデフォルトのキューバックエンドです。書き込みと読み出しが異なるリストに向けられるため、書き込みが1つである限り割り込みセーフです。postEventFromInterrupt()は、キューへの書き込みが1つの場合に割り込みから呼び出すことができる。複数のライタが存在する場合、postEvent()またはpostEventFromInterrupt()が、同じキューに対する別のpostEvent()またはpostEventFromInterrupt()によって割り込まれないようにしなければならない。process()は、postEvent()またはpostEventFromInterrupt()によって割り込まれても安全である。

std::threadとstd::mutexをサポートする組み込みプラットフォームでは、キューはmutexを使用することでスレッドセーフになります。

RTOS ベースのプラットフォームでは、キューのバックエンドの実装は RTOS 固有のキューに基づいており、これによりQul::EventQueue はマルチスレッド環境でスレッドセーフになります。

Qt Quick Ultraliteが提供するデフォルトのバックエンドは、memcpy() または同等のものを使用してデータをキューにコピーする。これは、EventQueue で使用されるデータ型が、POD、または古いデータでなければならないことを意味します。これができない場合は、代わりにポインタを使用しなければならない。しかし、Qt Quick Ultraliteによって提供されるバックエンドは、イベントがポインタである場合、メモリを管理しません。EventQueueOverrunPolicy_Discard 、onEventDiscarded を使用するか、上書きされるイベントのメモリを処理するカスタム・バックエンドを提供する必要があります。詳細はカスタムキューの実装を参照してください。

キューが保持できる以上のイベントを受信した場合、それらのイベントはEventQueueOverrunPolicy に従って処理されます。 さらに、clearOverrun を呼び出すことで状態がリセットされない限り、onQueueOverrun はいかなるイベントを処理する前にも呼び出されます。

EventQueueOverrunPolicy_Discard が使用され、破棄されたイベントが追加の処理を必要とする場合、onEventDiscarded 関数をオーバーライドすることができる。

例

EventQueue から派生して、特定のイベント・タイプのキューを作成し、onEvent をオーバーライドする：

#include <qul/eventqueue.h>

typedef int IntegerEvent;

class IntegerEventQueue : public Qul::EventQueue<IntegerEvent> {
    void onEvent(const IntegerEvent &event) override {
        // do some stuff with your event here
    }
};

次に、キューのインスタンスを作成する。QMLにデータやシグナルを公開するキューは、EventQueueの他にSingletonから派生することが多いので、このステップは不要です。

IntegerEventQueue integerEventQueue;

これで、割り込みコンテキストの外からイベントをポストできるようになりました：

integerEventQueue.postEvent(42);

割り込みハンドラからも：

integerEventQueue.postEventFromInterrupt(42);

キューサイズの調整

デフォルトでは、キューのサイズは5 に設定されています。 このサイズは、後続のディスパッチ操作の間に保存できるイベント数を決定します。ディスパッチはできるだけ早く、通常は次のアプリケーション・フレームで実行されます。EventQueueOverrunPolicy を使用して、キューが一杯になったときの動作を制御します。

// A queue where only the most recent event is interesting
Qul::EventQueue<IntegerEvent, Qul::EventQueueOverrunPolicy_OverwriteOldest, 1>

// A queue that can store many events
Qul::EventQueue<IntegerEvent, Qul::EventQueueOverrunPolicy_Discard, 1000>

オーバーランの通知を受けるには、onQueueOverrun メソッドをオーバーライドします。

class AudioQueue : public Qul::EventQueue<float, Qul::EventQueueOverrunPolicy_Discard, 1000>
{
    void onQueueOverrun() override {
        // Avoid the problem by reducing the frequency of event generation.
        setSampleRate(8000);
        clearOverrun();
    }
};

イベントの順序

各キュー内のイベントの順序は保持されますが、異なるキュー間での順序は保証されません。

これは、入力イベントなど、イベントの順序が重要な場合に問題となる可能性があります：

keyboardInput.postEvent(KeyEvents(...));
touchInput.postEvent(TouchEvent(...));
// Unknown whether the KeyEvent or TouchEvent is processed first!

このような場合は、別々のキューではなく、unionまたはstd::variantイベントタイプを持つ単一のキューを使用してください。