view release on metacpan or  search on metacpan

lib/POE/Component/Fuse.pm  view on Meta::CPAN

where the events arrive.

If this option is missing ( or POE is not running ) and "vfilesys" isn't enabled spawn() will return failure.

NOTE: You cannot use this and "vfilesys" at the same time! PoCo-Fuse will pick vfilesys over this! If this is the
case, then the session will only get the CLOSE event, not API requests.

The default is: calling session ( if POE is running ) when "vfilesys" isn't specified or error

=head3 vfilesys

The L<Filesys::Virtual> object to use as our filesystem. PoCo-Fuse will proceed to use L<Fuse::Filesys::Virtual>
to wrap around it and process the events internally.

Furthermore, you can also use L<Filesys::Virtual::Async> subclasses, this module understands their callback API
and will process it properly!

If this option is missing and "session" isn't enabled spawn() will return failure.

NOTE: You cannot use this and "session" at the same time! PoCo-Fuse will pick this over session!

Compatibility has not been tested with all Filesys::Virtual::XYZ subclasses, so please let me know if some isn't
working properly!

The default is: not used

=head2 Commands

There is only one command you can use, because this module does nothing except process FUSE events.

=head3 shutdown

Tells this module to kill the FUSE mount and terminates the session. Due to the semantics of FUSE, this
will often result in a wedged filesystem. You would need to either umount it manually ( via "fusermount -u $mount" )
or by enabling the "umount" option.

=head2 Events

If you aren't using the Filesys::Virtual interface, the FUSE api will be exposed to you in it's glory via
events to your session. You can process them, and send the data back via the supplied postback. All the arguments
are identical to the one in L<Fuse> so please take a good look at that module for more information!

The only place where this differs is the additional arguments. All events will receive 2 extra arguments in front
of the standard FUSE args. They are the postback and context info. The postback is self-explanatory, you
supply the return data to it and it'll fire an event back to PoCo-Fuse for processing. The context is the
calling context received from FUSE. It is a hashref with the 3 keys in it: uid, gid, pid. It is received via
the fuse_get_context() sub from L<Fuse>.

Remember that the events are the fuse methods with the prefix tacked on to them. A typical FUSE handler would
look something like the example below. ( it is sugared via POE::Session::AttributeBased hah )

	sub fuse_getdir : State {
		my( $postback, $context, $path ) = @_[ ARG0 .. ARG2 ];

		# somehow get our data, we fake it here for instructional reasons
		$postback->( 'foo', 'bar', 0 );
		return;
	}

Again, pretty please read the L<Fuse> documentation for all the events you can receive. Here's the list
as of Fuse v0.09: getattr readlink getdir mknod mkdir unlink rmdir symlink rename link chmod chown truncate
utime open read write statfs flush release fsync setxattr getxattr listxattr removexattr.

=head3 CLOSED

This is a special event sent to the session notifying it of component shutdown. As usual, it will be prefixed by the
prefix set in the options.

The event handler will get one argument, the error string. If you shut down the component, it will be "shutdown",
otherwise it will contain some error string. A sample handler is below.

	sub fuse_CLOSED : State {
		my $error = $_[ARG0];
		if ( $error ne 'shutdown' ) {
			print "AIEE: $error\n";

			# do some actions like emailing the sysadmin, restarting the component, etc...
		} else {
			# we told it to shutdown, so what do we want to do next?
		}

		return;
	}

=head2 Internals

=head3 XSification

This module does it's magic by spawning a subprocess via Wheel::Run and passing events back and forth to
the L<Fuse> module loaded in it. This isn't exactly optimal which is obvious, but it works perfectly!

I'm working on improving this by using XS but it will take me some time seeing how I'm a n00b :( Furthermore,
FUSE doesn't really help because I have to figure out how to get at the filehandle buried deep in it and expose
it to POE...

If anybody have the time and knowledge, please help me out and we can have fun converting this to a pure XS module!

=head3 Debugging

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

	sub POE::Component::Fuse::DEBUG () { 1 }
	use POE::Component::Fuse;


=head1 EXPORT

None.

=head1 SEE ALSO

L<POE>

L<Fuse>

L<Filesys::Virtual>

L<Fuse::Filesys::Virtual>

L<Filesys::Virtual::Async>