ocean.util.container.queue.NotifyingQueue

Queue that provides a notification mechanism for when new items were added

Generic interfaces and logic for RequestQueues and related classes.

Genericly speaking, a request handler delegate is being registered at the queue (ready()). The notifying queue will then call notify() to inform it about a new item added, notify() is expected to call pop() to receive that item. It should keep calling pop() until no items are left and then re-register at the queue and wait for another call to notify(). In other words:

1. NotifyingQueue.ready(&notify)

2. NotifyingQueue.ready calls notify()

3. notify() calls NotifyingQueue.pop();

* pop() returned a request: notify() processes data, back to 3.

* pop() returned null: continue to 4.

4. notify() calls NotifyingQueue.ready(&notify)

A more simple solution like this was considered:

1. NotifyingQueue.ready(&notify)

2. NotifyingQueue calls notify(Request)

3. notify() processes, back to 1.

But was decided against because it would cause a stack overflow for fibers, as a RequestHandler needs to call RequestQueue.ready() and if fibers are involved that call will be issued from within the fiber. If ready() calls notify again another processing of a request in the fiber will happen, causing another call to ready() leading to a recursion.

Now we require that the fiber calls pop in a loop.

Usage example for a hypothetical client who writes numbers to a socket

// Workaround: https://github.com/dlang/dub/issues/1761
module_ NotifyingQueueExample;

import ocean.util.container.queue.NotifyingQueue;

void main ( )
{
    auto notifying_queue = new NotifyingByteQueue(1024 * 40);

    void notee ( )
    {
        while (true)
        {
            auto popped = cast(char[]) notifying_queue.pop()

            if ( popped !is null )
            {
                Stdout.formatln("Popped from the queue: {}", popped);
            }
            else break;
        }

        notifying_queue.ready(&notee);
    }

    notifying_queue.ready(&notee);

    numbers.sendNumber(23);
    numbers.sendNumber(85);
    numbers.sendNumber(42);
}