Permalink
Browse files

Documentation and rename *::Child to *::Proc

  • Loading branch information...
1 parent 61debe3 commit 2b3c499e5357f8a2062720d9d957ded11598139f @exodist committed Jul 24, 2010
Showing with 252 additions and 269 deletions.
  1. +48 −91 README
  2. +64 −108 lib/Child.pm
  3. +2 −2 lib/Child/IPC/Pipe.pm
  4. +0 −61 lib/Child/Link/Child.pm
  5. +2 −2 lib/Child/Link/IPC/Pipe/{Child.pm → Proc.pm}
  6. +130 −0 lib/Child/Link/Proc.pm
  7. +6 −5 t/Manage.t
View
139 README
@@ -17,137 +17,94 @@ SYNOPSIS
use Child;
my $child = Child->new(sub {
- my $self = shift;
+ my ( $parent ) = @_;
....
# exit() is called for you at the end.
});
+ my $proc = $child->start
+
+ # Kill the child if it is not done
+ $proc->complete || $proc->kill(9);
+ $proc->wait; #blocking
+
+ IPC
# Build with IPC
my $child2 = Child->new(sub {
my $self = shift;
$self->say("message1");
$self->say("message2");
my $reply = $self->read(1);
}, pipe => 1 );
+ my $proc2 = $child2->start;
# Read (blocking)
- my $message1 = $child2->read();
- my $message2 = $child2->read();
+ my $message1 = $proc2->read();
+ my $message2 = $proc2->read();
- $child2->say("reply");
-
- # Kill the child if it is not done
- $child->complete || $child->kill(9);
-
- $child->wait; #blocking
+ $proc2->say("reply");
SHORTCUT
- Child can export the child(&) shortcut function when requested. This
- function creates and starts the child process.
+ Child can export the child() shortcut function when requested. This
+ function creates and starts the child process in one action.
use Child qw/child/;
- my $child = child {
- my $self = shift;
+
+ my $proc = child {
+ my $parent = shift;
...
};
You can also request IPC:
use Child qw/child/;
+
my $child = child {
- my $self = shift;
+ my $parent = shift;
...
} pipe => 1;
- To add IPC to children created with child() by default, import with
- ':pipe'. How child() behaves regarding IPC is lexical to each importing
- class.
-
- use Child qw/child :pipe/;
-
- my $child = child {
- my $self = shift;
- $self->say("message1");
- };
+DETAILS
+ First you define a child, you do this by constructing a Child object.
+ Defining a child does not start a new process, it is just the way to
+ define what the new process will look like. Once you have defined the
+ child you can start the process by calling $child->start(). One child
+ object can start as many processes as you like.
- my $message1 = $child->read();
+ When you start a child an Child::Link::Proc object is returned. This
+ object provides multiple useful methods for interacting with your
+ process. Within the process itself an Child::Link::Parent is created and
+ passed as the only parameter to the function used to define the child.
+ The parent object is how the child interacts with its parent.
-CLASS METHODS
- @children = Child->all_children()
- Get a list of all the children that have been started. This list is
- cleared in children when they are started.
+PROCESS MANAGEMENT METHODS
+ @procs = Child->all_procs()
+ Get a list of all the processes that have been started. This list is
+ cleared in processes when they are started; that is a child will not
+ list its siblings.
- @pids = Child->all_child_pids()
- Get a list of all the pids of children that have been started.
+ @pids = Child->all_proc_pids()
+ Get a list of all the pids of processes that have been started.
Child->wait_all()
- Call wait() on all children.
+ Call wait() on all processes.
+
+EXPORTS
+ $proc = child( sub { ... } )
+ $proc = child { ... }
+ $proc = child( sub { ... }, $plugin, @data )
+ $proc = child { ... } $plugin => @data
+ Create and start a process in one action.
CONSTRUCTOR
- $class->new( sub { ... } )
- $class->new( sub { ... }, pipe => 1 )
+ $child = Child->new( sub { ... } )
+ $child = Child->new( sub { ... }, $plugin, @plugin_data )
Create a new Child object. Does not start the child.
OBJECT METHODS
- $child->start()
+ $proc = $child->start()
Start the child process.
- $bool = $child->is_complete()
- Check if the child is finished (non-blocking)
-
- $child->wait()
- Wait on the child (blocking)
-
- $child->kill($SIG)
- Send the $SIG signal to the child process.
-
- $child->read()
- Read a message from the child.
-
- $child->write( @MESSAGES )
- Send the messages to the child. works like print, you must add "\n".
-
- $child->say( @MESSAGES )
- Send the messages to the child. works like say, adds the seperator
- for you (usually "\n").
-
- $child->autoflush( $BOOL )
- Turn autoflush on/off for the current processes write handle. This
- is on by default.
-
- $child->flush()
- Flush the current processes write handle.
-
- $child->pid()
- Returns the child PID (only in parent process).
-
- $child->exit_status()
- Will be undef unless the process has exited, otherwise it will have
- the exit status.
-
- Note: When you call exit($N) the actual unix exit status will be bit
- shifed with extra information added. exit_status() will shift the
- value back for you. That means exit_status() will return 2 whun your
- child calls exit(2) see unix_exit() if you want the actual value
- wait() assigned to $?.
-
- $child->unix_exit()
- When you call exit($N) the actual unix exit status will be bit
- shifed with extra information added. See exit_status() if you want
- the actual value used in exit() in the child.
-
- $child->code()
- Returns the coderef used to construct the Child.
-
- $child->parent()
- Returns the parent processes PID. (Only in child)
-
- $child->detach()
- Detach the child from the parent. uses POSIX::setsid(). When called
- in the child it simply calls setsid. When called from the parent the
- USR1 signal is sent to the child which triggers the child to call
- setsid.
-
HISTORY
Most of this was part of Parrallel::Runner intended for use in the
Fennec project. Fennec is being broken into multiple parts, this is one
Oops, something went wrong.

0 comments on commit 2b3c499

Please sign in to comment.