METHODS

named_recur(%args)

This is the preferred method to schedule recurring code in this framework. Typically called from within set_config(), it automatically ensures that only a single POE recurring event is setup, no matter how many times named_recur() is called.

Simply put: if your tasks has code that needs to run on an interval, use this method to schedule it.

The value in the 'recur_name' argument is used by this method to guard against unwanted redundant scheduling of a code reference.

That is, for all calls to named_recur inside a process space, there will be one and only one scheduled event per unique value of the argument 'recur_name'.

This method takes all named arguments:

recur_name (required) (process-globally unique string)

Process global unique identifier for a recurring POE event.

repeat_interval (required) (in seconds)

How often the work should repeat.

work (required) (CODE reference)

The Perl code that is run on an interval

tags (optional) (ARRAY reference of strings)

The list of tags associated with this recurring work. These are referenced by del_recurs() to deallocate scheduled POE events.

Example: (copied from lib/MultiModuleTest/Example1.pm in this distribution)

    $self->named_recur(
        recur_name => 'Example1',
        repeat_interval => 1, #runs every second
        work => sub {
            my $message = {
                ct => $self->{state}->{ct}++,
                outstr => $config->{outstr},
            };
            $self->emit($message);
        },
    }

del_recurs($tag)

Call this method to deallocate all of the previously scheduled POE events that contain the passed $tag.

NOTE NOTE NOTE

Because of the way POE scheduling works, it is possible and likely that a scheduled task could run one additional time AFTER del_recurs is called on it.

Example: $self->del_recurs('some_tag');

get_tags

Return an array reference of all of the tags that have been assigned to all of the currently scheduled POE events.

See NOTE in del_recurs(): a call to get_tags() immediately after a call to del_recurs() will NOT show the deleted tag, but it is possible that one or more delete scheduled events will run one additional time.

Example: foreach my $tag (@{$self->get_tags()) {

 }

recur(%args)

It is probably best to call named_recur().

This method actually does all of the scheduling work, and is called from named_recur(). However, named_recur() does the global named uniqueness check, and this method does not. So if you call this method directly, especially in set_config(), take care to not allow a build-up of POE events.

All of this method's arguments are the same as named_recur(), except it does not consider the recur_name field.

add_session($session_def)

get_multimodules_info

This returns a hash reference that contains information about every task that the MultiModule framework is aware of. 'aware of' is not limited to running and/or loaded. A MultiModule task module that exists in the configured search path, even though it is not referenced or configured, will also be in this structure.

The key to the return hash is the task name. The value is a reference to a hash that contains a variety of fields:

is_multimodule

Always true at this point; this is a legacy field that will be removed

is_stateful

Has a true value if the referenced task is stateful.

config

Contains undef if there is no config currently available for the task. Otherwise, this field contains the config for the task.

NOTE NOTE NOTE

At this time, calling this method from a task object will fail. It can only be called from the 'root', MultiModule object.

Example: while(my($task_name, $task_info) = each %{$root_object->get_multimodules_info}) {

 }

bucket($message)

This method is called to send data to the monitoring/management subsystem of MultiModule.

task_name

check_type

cutoff_age

min_points

min_bucket_span

bucket_name

bucket_metric

bucket_type

value

OUT OF BAND METHODS

The following methods are all a standardized interface to the Out Of Band subsystem, which is fully documented in perldoc App::MultiModule::Tasks::OutOfband

For all of the following methods (except send_oob()), the first, required argument is meant to be a relatively short, human readable 'summary', as appropriate. Key/value pairs can optionally be passed in as well, which are optionally accessible for viewing and/or filtering.

log($logstr, %optional_extra_info)

This method sends some information to the logging subsystem.

Example: $self->log('Something boring and relatively rare.', something => $else);

debug($debugstr, %optional_extra_info)

This method sends some information to the debugging subsystem.

Example: $self->debug("This $thing might be of interest", something => $else) if $self->{debug} > 2;

alert($lalertstr, %optional_extra_info)

This method sends some information to the alerting subsystem.

An alert() should always be 'actionable'. This is used by the MultiModule internal monitoring infrastructure to communicate resource violations, and when tasks are shutdown and failsafed.

Example: $self->alert("This $thing needs immediate attention", also => $this);

error($errorstr, %optional_extra_info)

This method sends some information to the error subsystem.

An error() should always be relevant, but it does not have to be 'actionable'. MultiModule sends these, for example, if a referenced task has a compile error or a run-time exception.

Example: $self->error('Something reasonably bad happened.', also => $this);

send_oob($oob_type, $oob_message)

This is the method that log, error, debug and alert all call. There can be any number of Out Of Band types. Think of each 'type' as a separate channel for messages that come out of MultiModule. These channels are configurably handled. As mentioned before, see perldoc App::MultiModule::Tasks::OutOfband for full documentation.

$oob_type A string that defines the OOB channel

$oob_message A HASH reference that is sent through the OOB channel

cpanm App::MultiModule

perl -MCPAN -e shell
install App::MultiModule