view release on metacpan or  search on metacpan

lib/AnyEvent/FDpasser.pm  view on Meta::CPAN

=head1 TESTS AND SYSTEM ASSUMPTIONS

All the following tests should work with BSD4.4, BSD4.3, and SysV interfaces (where available).


=head2 Bidirectional

A passer is bidirectional and can be used to both send and receive descriptors, even simultaneously.

There are tests (basic_socketpair.t and basic_filesystem.t) to verify this.


=head2 Non-blocking

A process may initiate push_recv_fh on a passer and this process will not block while it is waiting for the other end to call push_send_fh (and vice versa).

There are tests (recv_before_send.t and send_before_recv.t) to verify this.


=head2 FIFO ordering

The order descriptors are sent with push_send_fh is the same order that they are received on at the other end with push_recv_fh.

There is a test (buffer_exercise.t) to verify this and some other basic buffering properties.


=head2 Preserves blocking status

After a fork, the non-blocking status of a descriptor is preserved so if you are doing a socketpair followed by a fork it is acceptable to set the non-blocking status of both descriptors in the parent.

Also, the non-blocking status of a descriptor passed with this module is preserved after it is passed so it is not necessary to reset nonblocking status on descriptors.

There is a test (non_blocking_fhs.t) to verify this and some other assumptions for any given system.


=head2 Passing passers

Passing a descriptor and then using this descriptor as an argument to the existing_fh mode of this module to construct another passer is supported.

There is a test (send_passer_over_passer.t) to verify this assumption for any given system.


=head2 Descriptor table full

Even when the descriptor table fills up intermittently, no descriptors being passed should be lost.

There is a test (full_descriptor_table.t) to verify this.






=head1 SEE ALSO

L<The AnyEvent::FDpasser github repo|https://github.com/hoytech/AnyEvent-FDpasser>

This module gets its name from L<File::FDpasser> which does roughly the same thing as this module except this module provides a non-blocking interface, buffers the sending and receiving of descriptors, doesn't lose descriptors in the event of a full ...

L<Socket::PassAccessRights> is another module similar to File::FDpasser. It supports BSD4.3 and BSD4.4 interfaces.

L<Sprocket::Util::FDpasser> is an example of a non-blocking interface to File::FDpasser. It is based on L<POE> whereas this module is (obviously) based on AnyEvent.

A related module is L<Socket::MsgHdr> which provides complete control over ancillary data construction and parsing and is therefore useful for more than just passing descriptors. However, this module does not provide a non-blocking interface or buffe...



=head1 BUGS

This module doesn't support windows. Theoretically windows support could be added with some annoying combination of C<DuplicateHandle> and C<WSADuplicateSocket> but I don't care enough to implement it at this time.

If there are multiple outstanding filehandles to be sent, for performance reasons this module could (on BSD4.4 systems) batch them together into one C<cmsg> and then execute one C<sendmsg()> system call. Unfortunately, that would make the close-dup t...

It would be nice to auto-detect the best interface (BSD4.4/BSD4.3/SysV) to use for a given system.




=head1 AUTHOR

Doug Hoyte, C<< <doug@hcsw.org> >>

=head1 COPYRIGHT & LICENSE

Copyright 2012 Doug Hoyte.

This module is licensed under the same terms as perl itself.

=cut