NAME

AnyEvent::Filesys::Watcher::ReadDirectoryChanges::Queue - I/O Wrapper Around Thread::Queue

SYNOPSIS

use AnyEvent::Filesys::Watcher::FileSystemWatcher::Queue;
use IO::Select;

$q = AnyEvent::Filesys::Watcher::FileSystemWatcher::Queue->new;
$q->queue('foo', 'bar', 'baz');

# Get an IO::Handle for the queue.
$handle = $q->handle;
$q->pending;     # Returns 3.

# Or use IO for that:
$s = IO::Select->new;
$s->add($handle);
$s->can_read(0); # True. Data available.

$q->dequeue;     # Returns 'foo'.
$q->pending;     # Returns 2.
$s->can_read(0); # True. Still data available.

$q->dequeue(2);  # Returns ('foo', 'bar').
$q->pending;     # Returns 0;
$s->can_read(0); # False. No more data available.

DESCRIPTION

This is a wrapper around Thread::Queue which exposes a small subset of Thread;:Queue's API, more precisely, just enough API to pass it as a queue to Filesys::Notify::Win32::ReadDirectoryChanges. Only those methods that Filesys::Notify::Win32::ReadDirectoryChanges currently uses are implemented.

The module also wraps an IO::Handle with somewhat odd semantics. Whenever there is data pending in the queue, the handle will be ready to read. As soon as the queue is empty, the handle will block when being read from.

The sole motivation of this construct is to be able to integrate Filesys::Notify::Win32 with I/O multiplexing, for example with AE::io.

The module makes no effort to be thread-safe (if you want to call the Perl interpreter threads really threads). It is probably possible that the selectable handle that you get may signal that data is available but actually there is no data available. As a pre-caution, you should always check the queue with the pending() method before you actually read data with enqueue().

METHODS

new([ITEMS])

See "new" in Thread::Queue.

handle

Returns an IO::Handle that can be polled with select() (the 2nd variant that calls the select(2) syscall).

You can also read from this handle but this is unnecessary and dangerous.

It is unnecessary because dequeue() (see below) implicitely reads from the handle until it has no more data available. And what you can read from the handle is nonsense (currently an arbitrary number of "1" characters).

It is also dangerous, at least for single-threaded applications, because the call will block if there is no data available in the queue. For a single-threaded application that would lead to a deadlock, because while being blocked, no data can be enqueued.

enqueue(ITEMS)

See "enqueue" in Thread;:Queue.

dequeue([COUNT])

See "dequeue" in Thread;:Queue.

Note: Even if the handle() you have received is ready for reading, there is no absolute guarantee that there is really data available in the queue. Therefore, you should always call pending() before you dequeue data or your application will block.

pending

Returns the number of pending items in the queue, see "pending" in Thread;:Queue.

This method is actually not needed by Filesys::Notify::ReadDirectoryChanges but necessary for checking that there is really data available in the queue.

AUTHOR

Guido Flohr <guido.flohr@cantanea.com>.

SEE ALSO

Filesys::Notify::Win32::ReadDirectoryChanges, IO::Handle, Thread::Queue, perl(1)