Name

Class::Usul::IPC::Cmd - Execute system commands

Synopsis

   use Class::Usul::IPC::Cmd;

   sub run_cmd {
      my ($self, $cmd, @args) = @_; my $attr = arg_list @args;

      $attr->{cmd    } = $cmd or throw Unspecified, [ 'command' ];
      $attr->{log    } = $self->log;
      $attr->{rundir } = $self->config->rundir;
      $attr->{tempdir} = $self->config->tempdir;

      return Class::Usul::IPC::Cmd->new( $attr )->run_cmd;
   }

   $self->run_cmd( [ 'perl', '-v' ], { async => 1 } );

   # Alternatively there is a functional interface

   use Class::Usul::IPC::Cmd { tempdir => ... }, 'run_cmd';

   run_cmd( [ 'perl', '-v' ], { async => 1 } );

Description

Refactored IPC::Cmd with a consistent OO API

Would have used MooseX::Daemonize but using Moo not Moose so robbed some code from there instead

Configuration and Environment

Defines the following attributes;

async

Boolean defaults to false. If true the call to run_cmd will return without waiting for the child process to complete. If true the ignore_zombies attribute will default to true

close_all_files

Boolean defaults to false. If true and the detach attribute is also true then all open file descriptors in the child are closed except those in the keep_fhs list attribute

cmd

An array reference or a simple string. Required. The external command to execute

detach

Boolean defaults to false. If true the child process will double fork, set the session id and ignore hangup signals

err

A File::DataClass::IO object reference or a simple str. Defaults to null. Determines where the standard error of the command will be redirected to. Values are the same as for out. Additionally a value of 'out' will redirect standard error to standard output

expected_rv

Positive integer default to zero. The maximum return value which is considered a success

ignore_zombies

Boolean defaults to false unless the async attribute is true in which case this attribute also defaults to true. If true ignores child processes. If you plan to call waitpid to wait for the child process to finish you should set this to false

in

A File::DataClass::IO object reference or a simple str. Defaults to null. Determines where the standard input of the command will be redirected from. Object references should stringify to the name of the file containing input. A scalar is the input unless it is 'stdin' or 'null' which cause redirection from standard input and the null device

keep_fhs

An array reference of file handles that are to be left open in detached children

log

A log object defaults to an instance of Class::Null. Calls are made to it at the debug level

max_pidfile_wait

Positive integer defaults to 15. The maximum number of seconds the parent process should wait for the child's PID file to appear and be populated

nap_time

Positive number defaults to 0.3. The number of seconds to wait between testing for the existence of the child's PID file

out

A File::DataClass::IO object reference or a simple str. Defaults to null. Determines where the standard output of the command will be redirected to. Values include;

null

Redirect to the null device as defined by File::Spec

stdout

Output is not redirected to standard output

$object_ref

The object reference should stringify to the name of a file to which standard output will be redirected

partition_cmd

Boolean default to true. If the IPC::Run implementation is selected the command array reference will be partitioned on meta character boundaries unless this attribute is set to false

pidfile

A File::DataClass::IO object reference. Defaults to a temporary file in the configuration rundir which will automatically unlink when closed

rundir

A File::DataClass::IO object reference. Defaults to the tempdir attribute. Directory in which the PID files a stored

tempdir

A File::DataClasS::IO object reference. Defaults to tmpdir from File::Spec. The directory for storing temporary files

timeout

Positive integer defaults to 0. If greater then zero an alarm will be raised after this many seconds if the external command has not completed

use_ipc_run

Boolean defaults to false. If true forces the use of the IPC::Rum implementation

use_system

Boolean defaults to false. If true forces the use of the system implementation

working_dir

A File::DataClass::IO object reference. Defaults to null. If set the child will chdir to this directory before executing the external command

Subroutines/Methods

BUILDARGS

   $obj_ref = Class::Usul::IPC::Cmd->new( cmd => ..., out => ... );
   $obj_ref = Class::Usul::IPC::Cmd->new( { cmd => ..., out => ... } );
   $obj_ref = Class::Usul::IPC::Cmd->new( $cmd, out => ... );
   $obj_ref = Class::Usul::IPC::Cmd->new( $cmd, { out => ... } );
   $obj_ref = Class::Usul::IPC::Cmd->new( $cmd );

The constructor accepts a list of keys and values, a hash reference, the command followed by a list of keys and values, the command followed by a hash reference

BUILD

Set chomp and lock on the pidfile

run_cmd

   $response_object = Class::Usul::IPC::Cmd->run_cmd( $cmd, @args );

Can be called as a class method or an object method

Runs a given external command. If the command argument is an array reference the internal fork and exec implementation will be used, if a string is passed the IPC::Open3 implementation will be use instead

Returns a Class::Ususl::Response::IPC object reference

Diagnostics

Passing a logger object reference in with the log attribute will cause the run_cmd method to log at the debug level

Dependencies

Class::Null

File::DataClass

Module::Load::Conditional

Moo

Sub::Install

Try::Tiny

Unexpected

Incompatibilities

There are no known incompatibilities in this module

Bugs and Limitations

There are no known bugs in this module. Please report problems to http://rt.cpan.org/NoAuth/Bugs.html?Dist=Class-Usul. Patches are welcome

Acknowledgements

Larry Wall - For the Perl programming language

MooseX::Daemonize - Stole some code from that module

Author

Peter Flanigan, <pjfl@cpan.org>

License and Copyright

Copyright (c) 2016 Peter Flanigan. All rights reserved

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

This program is distributed in the hope that it will be useful, but WITHOUT WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE

cpanm Class::Usul

perl -MCPAN -e shell
install Class::Usul