The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

File::FDkeeper - Store open filehandles in another process for later use

SYNOPSIS

  # "server"
  my $fdk = new File::FDkeeper(Local => "/tmp/fdkeeper.sock") ; 
  $fdk->run() ;

  # "client"
  my $fdk = new File::FDkeeper(Peer => "/tmp/fdkeeper.sock") ;
  my $id = $fdk->put($some_fh) ;
  $fh = $fdk->get($id) ;
  $fdk->del($id) ;

DESCRIPTION

File::FDkeeper allows you to store open filehandles in a "server" process and retrieve them at a later time from another process.

When a filehandle is stored, an id is returned. This id can then be used by any other process to retrieve the filehandle (as long as they have permission to open the fifo).

CONSTRUCTORS

new ( [ARGS] )

Creates an File::FDkeeper object. new expects the following argument groups, in key-value pairs:

  Local                 Path to local fifo
  AccessTimeout         Filehandles not accessed since this number of seconds 
                          will be closed. Default is 0 (infinity).
  AccessTimeoutCheck    Frequency (in seconds) to check for expired 
                          filehandles. Default is 0 (never).

  Peer                  Path to peer fifo

If Local is specified, a "server" object is created.

If Peer is specified, a "client" object is created.

METHODS

put ( FILEHANDLE )

Stores FILEHANDLE and returns the associated id. An exception is thrown if an error occurs.

Note: when put is called from a "client" object, FILEHANDLE will be closed once it has been sent to the "server". This seems to be necesasry in order to be able to get and use that handle later in that process.

get ( ID )

Retrieves filehandle ID and returns it. Returns undef if filehandle ID is not presentily stored. An exception is thrown if an error occurs.

del ( ID )

Removes and closes filehandle ID. Returns undef if filehandle ID is not presently stored. An exception is thrown if an error occurs.

cnt ( )

Returns the number of filehandles currently in the "server". An exception is thrown if an error occurs.

run ( [LIFELINE] )

Note: This method is available only on the "server" objects.

Starts listening for connections on the fifo in order to store filehandles. Normally, this method does not return. However, if LIFELINE is a valid filehandle, run will return when any data (or EOF) is received on LIFELINE. If used, LIFELINE is normally a pipe used as such:

  use IO::Pipe ;

  my $pipe = new IO::Pipe() ;
  if (fork()){
    $pipe->reader() ;
    require File::FDkeeper ;
    my $fdk = new File::FDkeeper(Local => "/tmp/fdkeeper.sock") ;       
    $fdk->run($pipe) ;
    exit() ;
  }

  $pipe->writer() ;
  # do stuff...
  
  # When this process dies, the File::FDkeeper server process will 
  # die as well.

BUGS

File::FDpasser may write directly to STDERR on error. It doesn't seem that this can be suppressed.

SEE ALSO

File::FDpasser, IO::Socket::UNIX

AUTHOR

Patrick LeBoutillier, <patl@cpan.org>

COPYRIGHT AND LICENSE

Copyright 2005 by Patrick LeBoutillier

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