詳細な説明

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

一般に、イベントは、割り込みコンテキスト外では `postEvent ` 関数を使用して、割り込みハンドラ内では `postEventFromInterrupt ` 関数を使用して、キューに投稿できます。イベントを処理するには `onEvent ` をオーバーライドします。通常、処理は次のフレーム内に行われます。

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

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

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

Qt Quick Ultralite が提供するデフォルトのバックエンドは、memcpy() またはそれに相当する関数を使用して、データをキューにコピーします。つまり、EventQueue で使用されるデータ型は、POD（Plain Old Data）であるか、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 イベント型を使用した単一のキューを使用してください。