ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/AnyEvent-Fork-Pool/README
(Generate patch)

Comparing AnyEvent-Fork-Pool/README (file contents):
Revision 1.3 by root, Sun Apr 28 14:19:22 2013 UTC vs.
Revision 1.4 by root, Mon Nov 24 15:19:52 2014 UTC

1NAME 1NAME
2 AnyEvent::Fork::Pool - simple process pool manager on top of 2 AnyEvent::Fork::Pool - simple process pool manager on top of
3 AnyEvent::Fork 3 AnyEvent::Fork
4 4
5 THE API IS NOT FINISHED, CONSIDER THIS AN ALPHA RELEASE
6
7SYNOPSIS 5SYNOPSIS
8 use AnyEvent; 6 use AnyEvent;
7 use AnyEvent::Fork;
9 use AnyEvent::Fork::Pool; 8 use AnyEvent::Fork::Pool;
10 # use AnyEvent::Fork is not needed
11 9
12 # all possible parameters shown, with default values 10 # all possible parameters shown, with default values
13 my $pool = AnyEvent::Fork 11 my $pool = AnyEvent::Fork
14 ->new 12 ->new
15 ->require ("MyWorker") 13 ->require ("MyWorker")
… …
41 undef $pool; 39 undef $pool;
42 40
43 $finish->recv; 41 $finish->recv;
44 42
45DESCRIPTION 43DESCRIPTION
46 This module uses processes created via AnyEvent::Fork and the RPC 44 This module uses processes created via AnyEvent::Fork (or
47 protocol implement in AnyEvent::Fork::RPC to create a load-balanced pool 45 AnyEvent::Fork::Remote) and the RPC protocol implement in
48 of processes that handles jobs. 46 AnyEvent::Fork::RPC to create a load-balanced pool of processes that
47 handles jobs.
49 48
50 Understanding of AnyEvent::Fork is helpful but not critical to be able 49 Understanding of AnyEvent::Fork is helpful but not critical to be able
51 to use this module, but a thorough understanding of AnyEvent::Fork::RPC 50 to use this module, but a thorough understanding of AnyEvent::Fork::RPC
52 is, as it defines the actual API that needs to be implemented in the 51 is, as it defines the actual API that needs to be implemented in the
53 worker processes. 52 worker processes.
54 53
55EXAMPLES
56PARENT USAGE 54PARENT USAGE
57 To create a pool, you first have to create a AnyEvent::Fork object - 55 To create a pool, you first have to create a AnyEvent::Fork object -
58 this object becomes your template process. Whenever a new worker process 56 this object becomes your template process. Whenever a new worker process
59 is needed, it is forked from this template process. Then you need to 57 is needed, it is forked from this template process. Then you need to
60 "hand off" this template process to the "AnyEvent::Fork::Pool" module by 58 "hand off" this template process to the "AnyEvent::Fork::Pool" module by
… …
237 modifying them after the call and before the callback is invoked 235 modifying them after the call and before the callback is invoked
238 causes undefined behaviour. 236 causes undefined behaviour.
239 237
240 $cpus = AnyEvent::Fork::Pool::ncpu [$default_cpus] 238 $cpus = AnyEvent::Fork::Pool::ncpu [$default_cpus]
241 ($cpus, $eus) = AnyEvent::Fork::Pool::ncpu [$default_cpus] 239 ($cpus, $eus) = AnyEvent::Fork::Pool::ncpu [$default_cpus]
242 Tries to detect the number of CPUs ($cpus often called cpu cores 240 Tries to detect the number of CPUs ($cpus often called CPU cores
243 nowadays) and execution units ($eus) which include e.g. extra 241 nowadays) and execution units ($eus) which include e.g. extra
244 hyperthreaded units). When $cpus cannot be determined reliably, 242 hyperthreaded units). When $cpus cannot be determined reliably,
245 $default_cpus is returned for both values, or 1 if it is missing. 243 $default_cpus is returned for both values, or 1 if it is missing.
246 244
247 For normal CPU bound uses, it is wise to have as many worker 245 For normal CPU bound uses, it is wise to have as many worker
… …
249 CPU. Using hyperthreading is usually detrimental to performance, but 247 CPU. Using hyperthreading is usually detrimental to performance, but
250 in those rare cases where that really helps it might be beneficial 248 in those rare cases where that really helps it might be beneficial
251 to use more workers ($eus). 249 to use more workers ($eus).
252 250
253 Currently, /proc/cpuinfo is parsed on GNU/Linux systems for both 251 Currently, /proc/cpuinfo is parsed on GNU/Linux systems for both
254 $cpus and $eu, and on {Free,Net,Open}BSD, sysctl -n hw.ncpu is used 252 $cpus and $eus, and on {Free,Net,Open}BSD, sysctl -n hw.ncpu is used
255 for $cpus. 253 for $cpus.
256 254
257 Example: create a worker pool with as many workers as cpu cores, or 255 Example: create a worker pool with as many workers as CPU cores, or
258 2, if the actual number could not be determined. 256 2, if the actual number could not be determined.
259 257
260 $fork->AnyEvent::Fork::Pool::run ("myworker::function", 258 $fork->AnyEvent::Fork::Pool::run ("myworker::function",
261 max => (scalar AnyEvent::Fork::Pool::ncpu 2), 259 max => (scalar AnyEvent::Fork::Pool::ncpu 2),
262 ); 260 );
… …
266 more child-side function: 264 more child-side function:
267 265
268 AnyEvent::Fork::Pool::retire () 266 AnyEvent::Fork::Pool::retire ()
269 This function sends an event to the parent process to request 267 This function sends an event to the parent process to request
270 retirement: the worker is removed from the pool and no new jobs will 268 retirement: the worker is removed from the pool and no new jobs will
271 be sent to it, but it has to handle the jobs that are already 269 be sent to it, but it still has to handle the jobs that are already
272 queued. 270 queued.
273 271
274 The parentheses are part of the syntax: the function usually isn't 272 The parentheses are part of the syntax: the function usually isn't
275 defined when you compile your code (because that happens *before* 273 defined when you compile your code (because that happens *before*
276 handing the template process over to "AnyEvent::Fork::Pool::run", so 274 handing the template process over to "AnyEvent::Fork::Pool::run", so
277 you need the empty parentheses to tell Perl that the function is 275 you need the empty parentheses to tell Perl that the function is
278 indeed a function. 276 indeed a function.
279 277
280 Retiring a worker can be useful to gracefully shut it down when the 278 Retiring a worker can be useful to gracefully shut it down when the
281 worker deems this useful. For example, after executing a job, one 279 worker deems this useful. For example, after executing a job, it
282 could check the process size or the number of jobs handled so far, 280 could check the process size or the number of jobs handled so far,
283 and if either is too high, the worker could ask to get retired, to 281 and if either is too high, the worker could request to be retired,
284 avoid memory leaks to accumulate. 282 to avoid memory leaks to accumulate.
285 283
286 Example: retire a worker after it has handled roughly 100 requests. 284 Example: retire a worker after it has handled roughly 100 requests.
285 It doesn't matter whether you retire at the beginning or end of your
286 request, as the worker will continue to handle some outstanding
287 requests. Likewise, it's ok to call retire multiple times.
287 288
288 my $count = 0; 289 my $count = 0;
289 290
290 sub my::worker { 291 sub my::worker {
291 292
… …
294 295
295 ... normal code goes here 296 ... normal code goes here
296 } 297 }
297 298
298POOL PARAMETERS RECIPES 299POOL PARAMETERS RECIPES
299 This section describes some recipes for pool paramaters. These are 300 This section describes some recipes for pool parameters. These are
300 mostly meant for the synchronous RPC backend, as the asynchronous RPC 301 mostly meant for the synchronous RPC backend, as the asynchronous RPC
301 backend changes the rules considerably, making workers themselves 302 backend changes the rules considerably, making workers themselves
302 responsible for their scheduling. 303 responsible for their scheduling.
303 304
304 low latency - set load = 1 305 low latency - set load = 1
… …
330 331
331 high throughput, I/O bound jobs - set load >= 2, max = 1, or very high 332 high throughput, I/O bound jobs - set load >= 2, max = 1, or very high
332 When your jobs are I/O bound, using more workers usually boils down 333 When your jobs are I/O bound, using more workers usually boils down
333 to higher throughput, depending very much on your actual workload - 334 to higher throughput, depending very much on your actual workload -
334 sometimes having only one worker is best, for example, when you read 335 sometimes having only one worker is best, for example, when you read
335 or write big files at maixmum speed, as a second worker will 336 or write big files at maximum speed, as a second worker will
336 increase seek times. 337 increase seek times.
337 338
338EXCEPTIONS 339EXCEPTIONS
339 The same "policy" as with AnyEvent::Fork::RPC applies - exceptins will 340 The same "policy" as with AnyEvent::Fork::RPC applies - exceptions will
340 not be caught, and exceptions in both worker and in callbacks causes 341 not be caught, and exceptions in both worker and in callbacks causes
341 undesirable or undefined behaviour. 342 undesirable or undefined behaviour.
342 343
343SEE ALSO 344SEE ALSO
344 AnyEvent::Fork, to create the processes in the first place. 345 AnyEvent::Fork, to create the processes in the first place.
346
347 AnyEvent::Fork::Remote, likewise, but helpful for remote processes.
345 348
346 AnyEvent::Fork::RPC, which implements the RPC protocol and API. 349 AnyEvent::Fork::RPC, which implements the RPC protocol and API.
347 350
348AUTHOR AND CONTACT INFORMATION 351AUTHOR AND CONTACT INFORMATION
349 Marc Lehmann <schmorp@schmorp.de> 352 Marc Lehmann <schmorp@schmorp.de>

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines