Debian Codegraph @

README

raw
1 NAME
2
3 Child - Object oriented simple interface to fork()
4
5 DESCRIPTION
6
7 Fork is too low level, and difficult to manage. Often people forget to
8 exit at the end, reap their children, and check exit status. The
9 problem is the low level functions provided to do these things. Throw
10 in pipes for IPC and you just have a pile of things nobody wants to
11 think about.
12
13 Child is an Object Oriented interface to fork. It provides a clean way
14 to start a child process, and manage it afterwords. It provides methods
15 for running, waiting, killing, checking, and even communicating with a
16 child process.
17
18 NOTE: kill() is unpredictable on windows, strawberry perl sends the
19 kill signal to the parent as well as the child.
20
21 SYNOPSIS
22
23 BASIC
24
25 use Child;
26
27 my $child = Child->new(sub {
28 my ( $parent ) = @_;
29 ....
30 # exit() is called for you at the end.
31 });
32 my $proc = $child->start;
33
34 # Kill the child if it is not done
35 $proc->is_complete || $proc->kill(9);
36
37 $proc->wait; #blocking
38
39 IPC
40
41 # Build with IPC
42 my $child2 = Child->new(sub {
43 my $self = shift;
44 $self->say("message1");
45 $self->say("message2");
46 my $reply = $self->read(1);
47 }, pipe => 1 );
48 my $proc2 = $child2->start;
49
50 # Read (blocking)
51 my $message1 = $proc2->read();
52 my $message2 = $proc2->read();
53
54 $proc2->say("reply");
55
56 SHORTCUT
57
58 Child can export the child() shortcut function when requested. This
59 function creates and starts the child process in one action.
60
61 use Child qw/child/;
62
63 my $proc = child {
64 my $parent = shift;
65 ...
66 };
67
68 You can also request IPC:
69
70 use Child qw/child/;
71
72 my $child = child {
73 my $parent = shift;
74 ...
75 } pipe => 1;
76
77 DETAILS
78
79 First you define a child, you do this by constructing a Child object.
80 Defining a child does not start a new process, it is just the way to
81 define what the new process will look like. Once you have defined the
82 child you can start the process by calling $child->start(). One child
83 object can start as many processes as you like.
84
85 When you start a child an Child::Link::Proc object is returned. This
86 object provides multiple useful methods for interacting with your
87 process. Within the process itself an Child::Link::Parent is created
88 and passed as the only parameter to the function used to define the
89 child. The parent object is how the child interacts with its parent.
90
91 PROCESS MANAGEMENT METHODS
92
93 @procs = Child->all_procs()
94
95 Get a list of all the processes that have been started. This list is
96 cleared in processes when they are started; that is a child will not
97 list its siblings.
98
99 @pids = Child->all_proc_pids()
100
101 Get a list of all the pids of processes that have been started.
102
103 Child->wait_all()
104
105 Call wait() on all processes.
106
107 EXPORTS
108
109 $proc = child( sub { ... } )
110
111 $proc = child { ... }
112
113 $proc = child( sub { ... }, $plugin, @data )
114
115 $proc = child { ... } $plugin => @data
116
117 Create and start a process in one action.
118
119 CONSTRUCTOR
120
121 $child = Child->new( sub { ... } )
122
123 $child = Child->new( sub { ... }, $plugin, @plugin_data )
124
125 Create a new Child object. Does not start the child.
126
127 OBJECT METHODS
128
129 $proc = $child->start()
130
131 Start the child process.
132
133 SEE ALSO
134
135 Child::Link::Proc
136
137 The proc object that is returned by $child->start()
138
139 Child::Link::Parent
140
141 The parent object that is provided as the argument to the function
142 used to define the child.
143
144 Child::Link::IPC
145
146 The base class for IPC plugin link objects. This provides the IPC
147 methods.
148
149 HISTORY
150
151 Most of this was part of Parallel::Runner intended for use in the
152 Fennec project. Fennec is being broken into multiple parts, this is one
153 such part.
154
155 FENNEC PROJECT
156
157 This module is part of the Fennec project. See Fennec for more details.
158 Fennec is a project to develop an extendable and powerful testing
159 framework. Together the tools that make up the Fennec framework provide
160 a potent testing environment.
161
162 The tools provided by Fennec are also useful on their own. Sometimes a
163 tool created for Fennec is useful outside the greater framework. Such
164 tools are turned into their own projects. This is one such project.
165
166 Fennec - The core framework
167
168 The primary Fennec project that ties them all together.
169
170 AUTHORS
171
172 Chad Granum [email protected]
173
174 COPYRIGHT
175
176 Copyright (C) 2010 Chad Granum
177
178 Child is free software; Standard perl licence.
179
180 Child is distributed in the hope that it will be useful, but WITHOUT
181 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
182 FITNESS FOR A PARTICULAR PURPOSE. See the license for more details.
183