| … | |
… | |
| 364 | |
364 | |
| 365 | There is an important twist - the "AnyEvent::Fork::RPC::event" function |
365 | There is an important twist - the "AnyEvent::Fork::RPC::event" function |
| 366 | is only defined when the child is fully initialised. If you redirect the |
366 | is only defined when the child is fully initialised. If you redirect the |
| 367 | log messages in your "init" function for example, then the "event" |
367 | log messages in your "init" function for example, then the "event" |
| 368 | function might not yet be available. This is why the log callback checks |
368 | function might not yet be available. This is why the log callback checks |
| 369 | whether the fucntion is there using "defined", and only then uses it to |
369 | whether the function is there using "defined", and only then uses it to |
| 370 | log the message. |
370 | log the message. |
| 371 | |
371 | |
| 372 | PARENT PROCESS USAGE |
372 | PARENT PROCESS USAGE |
| 373 | This module exports nothing, and only implements a single function: |
373 | This module exports nothing, and only implements a single function: |
| 374 | |
374 | |
| … | |
… | |
| 412 | some requests and want the child to go away after it has handled |
412 | some requests and want the child to go away after it has handled |
| 413 | them. The problem is that the parent must not exit either until |
413 | them. The problem is that the parent must not exit either until |
| 414 | all requests have been handled, and this can be accomplished by |
414 | all requests have been handled, and this can be accomplished by |
| 415 | waiting for this callback. |
415 | waiting for this callback. |
| 416 | |
416 | |
| 417 | init => $function (default none) |
417 | init => $function (default: none) |
| 418 | When specified (by name), this function is called in the child |
418 | When specified (by name), this function is called in the child |
| 419 | as the very first thing when taking over the process, with all |
419 | as the very first thing when taking over the process, with all |
| 420 | the arguments normally passed to the "AnyEvent::Fork::run" |
420 | the arguments normally passed to the "AnyEvent::Fork::run" |
| 421 | function, except the communications socket. |
421 | function, except the communications socket. |
| 422 | |
422 | |
| … | |
… | |
| 426 | It is called very early - before the serialisers are created or |
426 | It is called very early - before the serialisers are created or |
| 427 | the $function name is resolved into a function reference, so it |
427 | the $function name is resolved into a function reference, so it |
| 428 | could be used to load any modules that provide the serialiser or |
428 | could be used to load any modules that provide the serialiser or |
| 429 | function. It can not, however, create events. |
429 | function. It can not, however, create events. |
| 430 | |
430 | |
| 431 | done => $function (default "CORE::exit") |
431 | done => $function (default: "CORE::exit") |
| 432 | The function to call when the asynchronous backend detects an |
432 | The function to call when the asynchronous backend detects an |
| 433 | end of file condition when reading from the communications |
433 | end of file condition when reading from the communications |
| 434 | socket *and* there are no outstanding requests. It's ignored by |
434 | socket *and* there are no outstanding requests. It is ignored by |
| 435 | the synchronous backend. |
435 | the synchronous backend. |
| 436 | |
436 | |
| 437 | By overriding this you can prolong the life of a RPC process |
437 | By overriding this you can prolong the life of a RPC process |
| 438 | after e.g. the parent has exited by running the event loop in |
438 | after e.g. the parent has exited by running the event loop in |
| 439 | the provided function (or simply calling it, for example, when |
439 | the provided function (or simply calling it, for example, when |
| … | |
… | |
| 575 | ( |
575 | ( |
| 576 | sub { Storable::nfreeze \@_ }, |
576 | sub { Storable::nfreeze \@_ }, |
| 577 | sub { @{ Storable::thaw shift } } |
577 | sub { @{ Storable::thaw shift } } |
| 578 | ) |
578 | ) |
| 579 | |
579 | |
|
|
580 | buflen => $bytes (default: "512 - 16") |
|
|
581 | The starting size of the read buffer for request and response |
|
|
582 | data. |
|
|
583 | |
|
|
584 | "AnyEvent::Fork::RPC" ensures that the buffer for reeading |
|
|
585 | request and response data is large enough for at leats aingle |
|
|
586 | request or response, and will dynamically enlarge the buffer if |
|
|
587 | needed. |
|
|
588 | |
|
|
589 | While this ensures that memory is not overly wasted, it |
|
|
590 | typically leads to having to do one syscall per request, which |
|
|
591 | can be inefficient in some cases. In such cases, it can be |
|
|
592 | beneficient to increase the buffer size to hold more than one |
|
|
593 | request. |
|
|
594 | |
|
|
595 | buflen_req => $bytes (default: same as "buflen") |
|
|
596 | Overrides "buflen" for request data (as read by the forked |
|
|
597 | process). |
|
|
598 | |
|
|
599 | buflen_res => $bytes (default: same as "buflen") |
|
|
600 | Overrides "buflen" for response data (replies read by the parent |
|
|
601 | process). |
|
|
602 | |
| 580 | See the examples section earlier in this document for some actual |
603 | See the examples section earlier in this document for some actual |
| 581 | examples. |
604 | examples. |
| 582 | |
605 | |
| 583 | $rpc->(..., $cb->(...)) |
606 | $rpc->(..., $cb->(...)) |
| 584 | The RPC object returned by "AnyEvent::Fork::RPC::run" is actually a |
607 | The RPC object returned by "AnyEvent::Fork::RPC::run" is actually a |
| … | |
… | |
| 608 | The following function is not available in this module. They are only |
631 | The following function is not available in this module. They are only |
| 609 | available in the namespace of this module when the child is running, |
632 | available in the namespace of this module when the child is running, |
| 610 | without having to load any extra modules. They are part of the |
633 | without having to load any extra modules. They are part of the |
| 611 | child-side API of AnyEvent::Fork::RPC. |
634 | child-side API of AnyEvent::Fork::RPC. |
| 612 | |
635 | |
|
|
636 | Note that these functions are typically not yet declared when code is |
|
|
637 | compiled into the child, because the backend module is only loaded when |
|
|
638 | you call "run", which is typically the last method you call on the fork |
|
|
639 | object. |
|
|
640 | |
|
|
641 | Therefore, you either have to explicitly pre-load the right backend |
|
|
642 | module or mark calls to these functions as function calls, e.g.: |
|
|
643 | |
|
|
644 | AnyEvent::Fork::RPC::event (0 => "five"); |
|
|
645 | AnyEvent::Fork::RPC::event->(0 => "five"); |
|
|
646 | &AnyEvent::Fork::RPC::flush; |
|
|
647 | |
| 613 | AnyEvent::Fork::RPC::event ... |
648 | AnyEvent::Fork::RPC::event (...) |
| 614 | Send an event to the parent. Events are a bit like RPC calls made by |
649 | Send an event to the parent. Events are a bit like RPC calls made by |
| 615 | the child process to the parent, except that there is no notion of |
650 | the child process to the parent, except that there is no notion of |
| 616 | return values. |
651 | return values. |
| 617 | |
652 | |
| 618 | See the examples section earlier in this document for some actual |
653 | See the examples section earlier in this document for some actual |
| … | |
… | |
| 620 | |
655 | |
| 621 | Note: the event data, like any data send to the parent, might not be |
656 | Note: the event data, like any data send to the parent, might not be |
| 622 | sent immediatelly but queued for later sending, so there is no |
657 | sent immediatelly but queued for later sending, so there is no |
| 623 | guarantee that the event has been sent to the parent when the call |
658 | guarantee that the event has been sent to the parent when the call |
| 624 | returns - when you e.g. exit directly after calling this function, |
659 | returns - when you e.g. exit directly after calling this function, |
| 625 | the parent might never receive the event. |
660 | the parent might never receive the event. See the next function for |
|
|
661 | a remedy. |
|
|
662 | |
|
|
663 | $success = AnyEvent::Fork::RPC::flush () |
|
|
664 | Synchronously wait and flush the reply data to the parent. Returns |
|
|
665 | true on success and false otherwise (i.e. when the reply data cannot |
|
|
666 | be written at all). Ignoring the success status is a common and |
|
|
667 | healthy behaviour. |
|
|
668 | |
|
|
669 | Only the "async" backend does something on "flush" - the "sync" |
|
|
670 | backend is not buffering reply data and always returns true from |
|
|
671 | this function. |
|
|
672 | |
|
|
673 | Normally, reply data might or might not be written to the parent |
|
|
674 | immediatelly but is buffered. This can greatly improve performance |
|
|
675 | and efficiency, but sometimes can get in your way: for example. when |
|
|
676 | you want to send an error message just before exiting, or when you |
|
|
677 | want to ensure replies timely reach the parent before starting a |
|
|
678 | long blocking operation. |
|
|
679 | |
|
|
680 | In these cases, you can call this function to flush any outstanding |
|
|
681 | reply data to the parent. This is done blockingly, so no requests |
|
|
682 | will be handled and no event callbacks will be called. |
|
|
683 | |
|
|
684 | For example, you could wrap your request function in a "eval" block |
|
|
685 | and report the exception string back to the caller just before |
|
|
686 | exiting: |
|
|
687 | |
|
|
688 | sub req { |
|
|
689 | ... |
|
|
690 | |
|
|
691 | eval { |
|
|
692 | ... |
|
|
693 | }; |
|
|
694 | |
|
|
695 | if ($@) { |
|
|
696 | AnyEvent::RPC::event (throw => "$@"); |
|
|
697 | AnyEvent::RPC::flush (); |
|
|
698 | exit; |
|
|
699 | } |
|
|
700 | |
|
|
701 | ... |
|
|
702 | } |
| 626 | |
703 | |
| 627 | PROCESS EXIT |
704 | PROCESS EXIT |
| 628 | If and when the child process exits depends on the backend and |
705 | If and when the child process exits depends on the backend and |
| 629 | configuration. Apart from explicit exits (e.g. by calling "exit") or |
706 | configuration. Apart from explicit exits (e.g. by calling "exit") or |
| 630 | runtime conditions (uncaught exceptions, signals etc.), the backends |
707 | runtime conditions (uncaught exceptions, signals etc.), the backends |
