Watch

Standard simple process loop

perls

Perl 100%

Find a file

Repository files (latest commit first)
Filename	Latest commit message	Latest commit date
Bernard Quatermass cce33995c8 Add explicit Provides to spec		2022-11-17 16:51:44 +00:00
dist	Add explicit Provides to spec	2022-11-17 16:51:44 +00:00
lib/Proc/Simple	Restructure to provide select() handling	2021-02-19 21:54:12 +00:00
LICENSE	Initial Checkin	2017-08-13 21:41:31 +01:00
Makefile.PL	typo	2021-02-19 21:56:20 +00:00
README.md	Restructure to provide select() handling	2021-02-19 21:54:12 +00:00

NAME

Proc::Simple::Loop - Provide a standard loop method with timed callback

VERSION

version 2.0

SYNOPSIS

    my $loop = Proc::Simple::Loop->new;

    my $vars->{'loop'} = $loop;

    $loop->run( \&mycallback, $vars );

    sub
    mycallback
    {
        my $vars = shift;
        # do stuff
        $vars->{'loop'}->stop
            if $vars->{'need_to_stop'};
        return;
    }

    # 
    my $loop = Proc::Simple::Loop->new( 'callback' => 'app_poll' );
    my $app = Some:App->new( 'loop' => $loop );
    $loop->run;

    # And in the app module
    sub
    app_poll
    {
        my $self = shift;
        
        ...
    }

    # Using file handles and select mode
    my $loop = Proc::Simple::Loop->new;
    my $app = MyApp->new( 'loop' => $loop,
                          'fd' => IO::File->new("watch_this","r"));
    $app->myFD( IO::File->new("watch_this","r") );
    $loop->add_read_handles( $app->fd );

    $loop->run( 'mycallback', $app );

    # In our MyApp class
    sub
    mycallback
    {
        my $self = shift;
        my $rhandles = shift; # array ref or readable handles
        my $whandles = shift; # array ref of writable handles
        my $xhandles = shift; # array ref of exception handles
        foreach( @$rhandles )
        {
            # read all the stuff from IO::Handle $_
        }
        # do stuff
        $self->loop->stop
            if $seld->need_to_stop;
        return;
    }

DESCRIPTION

Proc::Simple::Loop is a module to provide a standard timed loop with a callback and parameter.

PROPERTIES

poll_period: Get or set the poll period in seconds. Defaults to 1 second. If the select mechanism is used carefully then the poll period can safely be increased to something larger.
callback: Get or set the callback routine specified. Either a function reference or a method name. See run() method for details.
callback_arg: Get or set the extra argument used in the callback process. See run() method for details.

METHODS

run()

run( $callback, $callarg )

Performs the actual loop.

Optionally takes two parameters, the first being the callback routine, the second an argument to pass as its first parameter. Sets the callback and callback_arg properties.

There is some flexibility in how the callback is managed.

* If the callback is a reference it is presumed to be function reference and will simply be called with the callarg.

* If the callback is a scalar it is taken to be a method name. The callarg is presumed to be the object on which the method should be called. The ability to call will be checked to avoid crashing, but failure will mean there is no code handling the program requirements. If the callarg does handle the named method we test the loop object in case it can handle it (in the case where it has been subclassed).

Apart from the callarg (which becomes $self in the method call) there will be three additional arguments> These will be the three return values from the IO::Select-\select()> call, being array references to filehandles that are ready for read/write/exception processing respectively.

It is permissible to change the poll_period, callback and callback_arg parameters during the execution, but due care needs to be taken to ensure there is still a valid handler and that all tracked handles have their events cleared.

stop()

Signal the loop to terminate. Would normally be called from within callback routine or interrupt handler to allow clean unwrap from original caller.

Select Methods

In addition to a simple poll period, Proc::Simple::Loop can use a select() call and detect events on file handles and terminate the poll period early. In this mode the object maintains an IO::Select object for each of the three parameters, READ, WRITE, EXCEPTION. Handles can be added, removed and checked for via methods for each parameter. Details of the requirements can be found in the IO::Select documentation.

Care must be taken to ensure that any handle condition that triggers a return from a select is cleared otherwise it will still be true on the next poll which will terminate immediately and effectively make the process consume CPU.

add_read_handles( handles ... )

add_write_handles( handles ... )

add_excpt_handles( handles ... )

Adds handles to the IO::Select object for this function.

Takes a list of handles to add from the object.

remove_add_handles( handles ... )

remove_write_handles( handles ... )

remove_excpt_handles( handles ... )

Remove handles from the IO::Select object for this function.

Takes a list of handles to remove from the object.

exists_add_handle( handle )

exists_write_handle( handle )

exists_excpt_handle( handle )

Checks for the existence of a given handles on the IO::Select object for this function.

Takes a single handle and returns true if the handle is on the object.

reset_all_handles()

This method discards all three of the current IO::Select objects, creates new instances.

This can be used to reinitialise the state.

COMPATIBILITY

Proc::Simple::Loop requires Class::Accessorize.

AUTHOR

Bernard Quatermass <toolsmith@quatermass.co.uk>

COPYRIGHT AND LICENSE

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

</html>