NAME

RPC::ExtDirect::Server::Util - Ext.Direct server utility functions

SYNOPSIS

Using in test scripts

    use Test::More tests => n;
    use RPC::ExtDirect::Server::Util;
    
    my ($host, $port) = maybe_start_server();
    ok $port, "Got host: $host and port: $port";
    
    ...
    
    # Optional, will be called automatically
    stop_server()

Running test scripts

Run with no command line options to fork a child process, instantiate a new server and run the tests against the child process (normal mode):

    perl t/01_test.t
    
    1..x
    
    ...

Debugging test scripts

In one terminal session, run a script in debugging mode:

    perl t/01_test.t -fet 1
    
    1..x
    RPC::ExtDirect::Server is listening on 127.0.0.1:31302

    Loading DB routines from perl5db.pl version 1.33
    Editor support available.
    
    DB<1>

In another terminal session, run the same script against the process started above by specifying the port it listens on:

    perl t/01_test.t -p 31302
    
    1..x
    ...

DESCRIPTION

This package contains utility functions for starting and stopping RPC::ExtDirect::Server instances. It is most commonly used in test scripts, both for running the tests and debugging the code when test failures happen.

EXPORTED SUBROUTINES

This package exports the following functions:

start_server

Start a new instance of RPC::ExtDirect::Server or derived class, wait for it to bind to a port and return the actual host and port number values. If an instance has already been started, return its host and port.

The server instance by default will be started in background (forked process), or optionally in foreground. See "foreground" parameter below.

If a port to listen to was not specified in arguments, a random value between 30,000 and 40,000 will be generated. If the server instance is unable to bind to the generated port, a new random value will be generated and a new attempt to bind to that port will be made, until an unused port is found.

If a port value was provided in arguments, but the server is unable to bind to that port, no attempts will be made to bind to another port; start_server will die with an error.

This function returns ($host, $port) values in list context, or "$host:$port" string in scalar context.

The following arguments are accepted by name in a hash:

server_class

Name of the class to use instead of RPC::ExtDirect::Server when instantiating a new server object. This should be a subclass of RPC::ExtDirect::Server.

timeout

Interval in seconds to wait for the server to bind to a port; after that the child process will be killed and start_server will die with an error.

This parameter defaults to 30 seconds and is only meaningful when server is started in background.

foreground

If set to a truthy value the server instance will be instantiated and executed in the current process, instead of forking a child process.

enbugger

If set to a truthy value, an attempt will be made to require the Enbugger module.

set_timer

Interval in seconds to wait before dropping to debugger prompt by calling Enbugger->stop(). This is useful to set breakpoints after the server has been initialized and bound to a port. Usually 1 second is enough for this, but starting up may take longer when heavyweight modules like Moose are used in your code.

other

Any other arguments are passed to the "server_class" constructor. See "new" in RPC::ExtDirect::Server for more information.

maybe_start_server

This function will process command line options from @ARGV and optionally start a new server instance by calling "start_server".

If the "-p" option was given, the host and port will be returned immediately instead of attempting to start a server. This allows using the the same function both to debug test scripts and run them normally; see examples in "SYNOPSIS".

This function accepts named arguments in a hash; all arguments will be passed to "start_server" except when modified by command line options described below:

-h

Host name or IP address to use either when starting a server process, or connecting to a separately started process. Defaults to 127.0.0.1.

See "host" in "start_server".

-p

Port number that should be used to connect to a separately started server process. Specifying this option will cause "maybe_start_server" to return the host and port immediately instead of trying to start a new server instance.

-l

Port number to bind to when starting a new process. If no port number is given, a random port will be generated.

See "port" in "start_server".

-s

Directory to use as the static content root; the value will be passed to the server constructor as static_dir parameter. See "new" in RPC::ExtDirect::Server.

-f

Run the server instance in foreground instead of in a forked process.

See "foreground" parameter in "start_server".

-e

Require the Enbugger module.

See "enbugger" parameter in "start_server".

-t

Interval in seconds to wait before dropping into debugger prompt.

See "set_timer" parameter in "start_server".

stop_server

Stop the server instance in a forked child process, if it has been started already. This function accepts an optional process id number of the child process.

This function will be called automatically in an END block to ensure that the server instance has been stopped when the script finishes. This automatic cleanup can be prevented; see "no_shutdown".

This function is not exported:

no_shutdown

Pass a truthy value to this function to prevent automatic server instance cleanup:

    RPC::ExtDirect::Server::Util::no_shutdown(1);

SEE ALSO

This module and its functions are used heavily in Test::ExtDirect.