Filesys::Virtual::Async::Dispatcher - Multiple filesystems mounted on a single filesystem


        use strict; use warnings;
        use Fcntl qw( :DEFAULT :mode ); # S_IFREG S_IFDIR, O_SYNC O_LARGEFILE etc

        # uncomment this to enable debugging
        #sub Filesys::Virtual::Async::Dispatcher::DEBUG { 1 }

        use Filesys::Virtual::Async::Plain;
        use Filesys::Virtual::Async::Dispatcher;

        # create the root filesystem
        my $rootfs = Filesys::Virtual::Async::Plain->new( 'root' => $ENV{'PWD'} );

        # create the extra filesystems
        my $tmpfs = Filesys::Virtual::Async::Plain->new( 'root' => '/tmp' );
        my $procfs = Filesys::Virtual::Async::Plain->new( 'root' => '/proc' );

        # put it all together
        my $vfs = Filesys::Virtual::Async::Dispatcher->new( 'rootfs' => $rootfs );
        $vfs->mount( '/tmp', $tmpfs );
        $vfs->mount( '/tmp/proc', $procfs );

        # use $vfs as you wish!
        $vfs->readdir( '/tmp/proc', sub {       # should access the $procfs object
                my $data = shift;
                if ( defined $data ) {
                        foreach my $e ( @$data ) {
                                print "entry in /tmp/proc -> $e\n";
                        print "end of listing for /tmp/proc\n";
                } else {
                        print "error reading /tmp/proc\n";
        } );


Using this module will enable you to "mount" objects onto a filesystem and properly map methods to them.


This module allows you to have arbitrary combinations of Filesys::Virtual::Async objects mounted and expose a single filesystem. The dispatcher will correctly map methods to the proper object based on their path in the filesystem. This works similar to the way linux manages mounts in a single "visible" filesystem.

It might be a bit confusing on how the paths work at first. I'm sure with a bit of experimentation and looking at the documentation for the Filesys::Virtual::Async::XYZ subclass, you'll get it!

This module makes extensive use of the functions in File::Spec to be portable, so it might trip you up if you are developing on a linux box and trying to mount '/foo' on a win32 box :)

Initializing the dispatcher

This constructor accepts either a hashref or a hash, valid options are:


This sets the Filesys::Virtual::Async object that will manage the "root" filesystem.

If this argument is undefined or not a proper subclass of Filesys::Virtual::Async new() will die.


There is only two methods you can use, because this module does nothing except dispatch method calls to the proper object.


Mounts a new Filesys::Virtual::Async object on the rootfs. Takes two arguments: the path and the object.

Returns true on success, false on failure.

Possible failure reasons:

undefined path
undefined object or not proper subclass of Filesys::Virtual::Async
another object already mounted on path

NOTE: This module is currently a bit stupid. It will allow mounts on non-existent directories! This could cause weirdness when trying to do operations on the parent directory. This will be rectified in a future version, once I get my head around the callbacks and figure out a new API to mount with a callback...


Unmounts a mounted Filesys::Virtual::Async object. Takes one argument: the path.

Returns true on success, false on failure.

Special Cases

Currently, this module does a pretty good job of dispatching methods to the proper object. However, there are some methods which have exceptions to this rule.


Unimplemented, please do it directly on the object you are mounting onto the dispatcher.


Array mode not supported because it would require extra munging on my part to get the paths right.

Linking across mounts is not supported because it would be crazy to keep the mapping in the dispatcher.


Doing these operations across mounts is not supported. Theoretically I could implement this in the dispatcher but it would have to happen in a future version :)


Deleting a directory which contains another mount in it is not supported. This could be done but we would have to dig into the AIO code to make sure it stops deleting when it encounters the submount...


You can enable debug mode which prints out some information ( and especially error messages ) by doing this:

        sub Filesys::Virtual::Async::Dispatcher::DEBUG () { 1 }
        use Filesys::Virtual::Async::Dispatcher;






You can find documentation for this module with the perldoc command.

    perldoc Filesys::Virtual::Async::Dispatcher



Please report any bugs or feature requests to bug-filesys-virtual-async-dispatcher at, or through the web interface at I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.


Apocalypse <>

Props goes to xantus who got me motivated to write this :)


Copyright 2010 by Apocalypse

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.