/ 
IPC-Door-0.11
River stage zero No dependents
/ IPC::Door

NAME

IPC::Door - Interface to Solaris (>= 2.6) Door library

SYNOPSIS

The server script:

use IPC::Door::Server;
use Fcntl;
my  $door = "/path/to/door";
my  $dserver = new IPC::Door::Server($door, &mysub);
while (1) {
    die "$door disappeared: $!\n" unless IPC::Door::is_door($door);
    sysopen( DOOR, $door, O_WRONLY ) || die "Can't write to $door: $!\n";
    close DOOR;
    select undef, undef, undef, 0.2;
}

sub mysub {
    my $arg = shift;
    # do something
    my $ans;
    return $ans;
}

The client script:

use IPC::Door::Client;
use Fcntl;
my  $door = "/path/to/door";
my  $dclient = new IPC::Door::Client($door);
my  $data;
my  $answer = $client->call($data, O_RDWR);

ABSTRACT

IPC::Door is a Perl extension to the door library present in Solaris 2.6 and later.

COMMON CLASS METHODS

new

The method new initializes the object, taking a mandatory argument $path. Each IPC::Door::* object is thus associated with a door through which it communicates with a server (if the object is a ::Client) or a client (if the object is a ::Server).

In addition, the IPC::Door::Server object requires a reference to a code block &mysub, which will be a part of the server process upon compilation. See IPC::Door::Server.

is_door

$dserver->is_door;

IPC::Door::is_door('/path/to/door');

Subroutine is_door can be called either as an object method or as a subroutine.

If the former, it determines if the path name assoicated with the object is a door. In the latter case, it determines if the path name passed to it is a door.

info

my ($target, $attr, $uniq) = IPC::Door::info($door);

Subroutine info takes the path to a door and return array ($target, $attributes, $uniquifer). $target is the server process id that is listening through the door. $attributes is the integer that represents the attributes of the door (see "Door attributes"), and $uniquifer is the system-wide unique number associated with the door.

Door attributes

When testing for a door's attributes, it is convenient to import some symbols:

use IPC::Door qw( :attr );

This imports symbols DOOR_ATTR_MASK DOOR_CREATE_MASK DOOR_DELAY DOOR_IS_UNREF DOOR_KI_CREATE_MASK DOOR_LOCAL DOOR_PRIVATE DOOR_REVOKED DOOR_UNREF DOOR_UNREF_ACTIVE DOOR_UNREF_MULTI

Note that not all symbols are available in all versions of Solaris.

KNOWN ISSUES

1. Incomaptible with threaded perl

I know this module does not work nicely if perl was configured with -Dusethreads option. I know that the precompiled package from http://www.blastwave.org has this option set. I am not sure about the one from http://www.sunfreeware.com.

2. Compatibility with other door clients and servers

The doors created by IPC::Door::Server evaluates the passed data in the scalar context before passing it to the door server. If you want to pass complex data structures, use the Storable module, which is standard as of Perl 5.8.0.

Data an IPC::Door::Server object returns are probably incomprehensible and useless for non-IPC::Door::Client processes. You can read the source to find out exactly what are passed around, but it might not be worth your while to do that, when you can simply use IPC::Door::Client. (And of course, I might change the internal data structure in the future.)

Conversely, IPC::Door::Client can read data from doors created by non-IPC::Door::Server processes, but it is entirely up to the IPC::Door::Client process to make sense of what's read.

3. Some door_* routines not implemented

Some door library routines door_bind, door_revoke, door_server_create, and door_unbind still need to be implemented. These routines contribute to custom door server creation, which may be too complicated and unnecessary for this module's needs; if such a fine control over the server creation process is required, perhaps you should be writing your utility in C! If you are really interested in this sort of thing, contact the author.

door_info is only partially implemented.

4. Incomplete error checking

There should be more robust error checking and more friendly error messages throughout.

5. Limited testing

IPC::Door has been tested on Solaris 8 (with Sun Workshop compiler), 9 (with gcc 3.3), and 10 (with gcc 4.0.0) (all on SPARC).

I need more testing on following configurations (both SPARC and x86 unless otherwisse noted):

  • Solaris 9 and 10 with Sun ONE Studio compiler (or whatever Sun calls its C compiler these days).

  • 64-bit perl executable.

  • Threaded perl. (See above.)

  • Solaris 10 on x86.

Please let me know if you can help me test the module on these configurations.

6. A little inconsistent XS code

I'm still a beginner at XS (some may argue also at Perl), so the code, especially the XS portion, can be improved. Any suggestions are welcome.

7. Unicode compatibility

In my limited testing, I found that this module has difficulty dealing with Unicode data.

SEE ALSO

IPC::Door::Client, IPC::Door::Server

door_bind(3DOOR) (http://docs.sun.com/db/doc/817-0697/6mgfsdh3m?a=view),

door_call(3DOOR) (http://docs.sun.com/db/doc/817-0697/6mgfsdh3n?a=view),

door_create(3DOOR) (http://docs.sun.com/db/doc/817-0697/6mgfsdh3n?a=view),

door_cred(3DOOR) (http://docs.sun.com/db/doc/817-0697/6mgfsdh3p?a=view),

door_info(3DOOR) (http://docs.sun.com/db/doc/817-0697/6mgfsdh3q?a=view),

door_return(3DOOR) (http://docs.sun.com/db/doc/817-0697/6mgfsdh3r?a=view),

door_revoke(3DOOR) (http://docs.sun.com/db/doc/817-0697/6mgfsdh3s?a=view),

door_server_create(3DOOR) (http://docs.sun.com/db/doc/817-0697/6mgfsdh3t?a=view),

door_ucred(3DOOR) (http://docs.sun.com/app/docs/doc/816-5171/6mbb6dcnk?a=view),

door_unbind(3DOOR) (http://docs.sun.com/db/doc/817-0697/6mgfsdh3u?a=view),

UNIX Network Programming Volume 2: Interprocess Communications (http://www.kohala.com/start/unpv22e/unpv22e.html)

Solaris Internals: Core Kernel Architecture (http://www.solarisinternals.com)

AUTHOR

ASARI Hirotsugu <asarih at cpan dot org>

(http://www.asari.net/perl)

COPYRIGHT AND LICENSE

Copyright 2003-2005 by ASARI Hirotsugu

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