Free subroutine software for linux

Sub::Timebound is a Perl extension for timebound computations.

SYNOPSIS

use Sub::Timebound;

sub fun
{
my $i = shift;
if ($i =~ /7$/) {
die "Simulated internal errorn";
}
while ($i) {
$i--;
}
return "All is well";
}

my $x = timeboundretry(10, 3, 5, &fun, 10);
### Returns { value => ..., status => 0(FAILURE)/1(SUCCESS) }
### value is the return value of fun()

if ($x->{status}) {
# SUCCESS
$x->{value}
} else {
# FAILURE
}

Module exports "timeboundretry" - this is a wrapper that watches a function call.

my $x = timeboundretry([TimeAllocated], [NumberOfAttempts],
[PauseBetweenAttempts],[CodeRef],[Param1], [Param2], ...);


[TimeAllocated] - Seconds allocated to [CodeRef] to complete
[NumberOfAttempts] - Number of attempts made to [CodeRef]
[PauseBetweenAttempts] - Seconds to wait before making subsequent attempts
[CodeRef] - Reference to subroutine
[Param1]... - Parameters to subroutine

B::Utils is a helper functions for op tree manipulation.

SYNOPSIS

use B::Utils;


These functions make it easier to manipulate the op tree.

FUNCTIONS

all_starts

all_roots

Returns a hash of all of the starting ops or root ops of optrees, keyed to subroutine name; the optree for main program is simply keyed to __MAIN__.

Note: Certain "dangerous" stashes are not scanned for subroutines: the list of such stashes can be found in @B::Utils::bad_stashes. Feel free to examine and/or modify this to suit your needs. The intention is that a simple program which uses no modules other than B and B::Utils would show no addition symbols.

This does not return the details of ops in anonymous subroutines compiled at compile time. For instance, given

$a = sub { ... };

the subroutine will not appear in the hash. This is just as well, since theyre anonymous... If you want to get at them, use...

anon_subs()

This returns an array of hash references. Each element has the keys "start" and "root". These are the starting and root ops of all of the anonymous subroutines in the program.

$op->oldname

Returns the name of the op, even if it is currently optimized to null. This helps you understand the stucture of the op tree.

$op->kids

Returns an array of all this ops non-null children, in order.

$op->first
$op->last
$op->other

Normally if you call first, last or other on anything which is not an UNOP, BINOP or LOGOP respectivly it will die. This leads to lots of code like:

$op->first if $op->can(first);

B::Utils provides every op with first, last and other methods which will simply return nothing if it isnt relevent.

$op->parent

Returns the parent node in the op tree, if possible. Currently "possible" means "if the tree has already been optimized"; that is, if were during a CHECK block. (and hence, if we have valid next pointers.)

In the future, it may be possible to search for the parent before we have the next pointers in place, but itll take me a while to figure out how to do that.

$op->previous

Like $op->next, but not quite.

walkoptree_simple($op, &callback, [$data])

The B module provides various functions to walk the op tree, but theyre all rather difficult to use, requiring you to inject methods into the B::OP class. This is a very simple op tree walker with more expected semantics.

The &callback is called at each op with the op itself passed in as the first argument and any additional $data as the second.

All the walk functions set $B::Utils::file and $B::Utils::line to the appropriate values of file and line number in the program being examined. Since only COPs contain this information it may be unavailable in the first few callback calls.

walkoptree_filtered($op, &filter, &callback, [$data])

This is much the same as walkoptree_simple, but will only call the callback if the filter returns true. The filter is passed the op in question as a parameter; the opgrep function is fantastic for building your own filters.

walkallops_simple(&callback, [$data])

This combines walkoptree_simple with all_roots and anon_subs to examine every op in the program. $B::Utils::sub is set to the subroutine name if youre in a subroutine, __MAIN__ if youre in the main program and __ANON__ if youre in an anonymous subroutine.

walkallops_filtered(&filter, &callback, [$data])

Same as above, but filtered.

Sub::Curry is a Perl module to create curried subroutines.

SYNOPSIS

use Sub::Curry;
use Sub::Curry qw/ :CONST curry /; # Import spice constants
# and the &curry function.

#my $f1 = Sub::Curry::->new(&foo, 1, 2); # Same as below.
my $f1 = curry(&foo, 1, 2);
my $f2 = $cb1->new(3, 4);

my $f3 = curry(&foo, 1, HOLE, 3);
my $f4 = $f3->new(2, 4);

$f1->(a); # foo(1, 2, a);
$f2->(a); # foo(1, 2, 3, 4, a);

$f3->(a); # foo(1, a, 3);
$f4->(a); # foo(1, 2, 3, 4, a);

$f4->call(a); # Same as $cb4->(a);

Sub::Curry is a module that provides the currying technique known from functional languages. This module, unlike many other modules that borrow techniques from functional languages, doesnt try to make Perl functional. Instead it tries to make currying Perlish.

This module aims to be a base for other modules that use/provide currying techniques.

This module supports a unique set of special spices (argument features). It doesnt just support holes, but also introduces antiholes, blackholes, whiteholes, and antispices. All these extra special spices effect how the spice is applied to the subroutine. They make functions such as &rcurry superfluous. See "Currying" and Sub::Curry::Cookbook.

An oft-missed feature is argument aliasing. This module preserves the aliasing.
Sub::Curry does explicit currying. For more automatic ways to use currying, look in the Sub::Curry::* namespace.

When version hits 1.00 the interface will be stable.

Sub::PatMat can call a version of subroutine depending on its arguments.
SYNOPSIS
use Sub::PatMat;
# basics:
sub fact : when($_[0] $b) { 1 }
print join ", ", sort mysort (3,1,2);
# intuiting parameter names:
sub dispatch : when($ev eq "help") { my ($ev) = @_; print "helpn" }
sub dispatch : when($ev eq "blah") { my ($ev) = @_; print "blahn" }
dispatch("help");
dispatch("blah");
# no fallback, this will die:
dispatch("hest"); # dies with "Bad match"
# silly
sub do_something : when(full_moon()) { do_one_thing() }
sub do_something { do_something_else() }
The Sub::PatMat module provides the programmer with the ability to define a subroutine multiple times and to specify what version of the subroutine should be called, depending on the parameters passed to it (or any other condition).
This is somewhat similar to argument pattern matching facility provided by many programming languages.
To use argument pattern matching on a sub, the programmer has to specify the when attribute. The parameter to the attribute must be a single Perl expression.
When the sub is called, those expressions are evaluated consequitively until one of them evaluates to a true value. When this happens, the corresponding version of a sub is called.
If none of the expressions evaluates to a true value, a Bad Match exception is thrown.
It is possible to specify a fall-back version of the function by doing one of the following:
specifying when without an expression
specifying when with an empty expression
not specifying the when attribute at all
Please note that it does not make sense to specify any non-fall-back version of the sub after the fall-back version, since such will never be called.
There is an additional limitation for the last form of the fall-back version (the one without the when attribute at all), namely, it must be the last version of the sub defined.
It is possible to specify named sub parameters in the when-expression. This facility is highly experimental and is currently limited to scalar parameters only. The named sub parameters are extracted from expressions of the form
my (parameter list) = @_;
anywhere in the body of the sub.
Version restrictions:
- The ability to intuit parameter names is very limited and without doubts buggy.
- The when attribute condition is limited to a single Perl expression.
Enhancements:
- Perl

Language::Zcode::Runtime::State is a Perl module to handle saving, restoring, etc. the game state.

restoring

Getter/setter: currently in the process of restoring or not?

start_machine

Start executing the Z-machine.

In the normal case (starting a new game, or restarting), this is as simple as calling the Z-machine subroutine whose address is stored in the header.
If were restoring from a save file, its more complicated. See "resume_execution".

z_call

Wrapper around Z-code subroutine calls. The main reason we need it is for save/restore.

In the normal case, z_call just calls the Z-code subroutine at address arg0 with the given args (arg5-argn), if any. Args 1-4 arent used by z_call, but (hack alert!) they go into the Perl call stack, which is needed for saving Z-machine state.

Input: subroutine address to call, local variables & eval stack (arrayrefs), next PC, store variable, args to the Z-sub.

See "The call stack" for far more detail on this sub and save/restore.

save_state

Implement the @save opcode, saving the current Z-machine state (as opposed to writing a table to a file, the other use of the @save opcode)

Note that this sub also gets called at the very end of the restoring process.

Returns 0 for failed save, 1 for successful save, 2 for "just finished restoring".

build_save_stack

Create a Z-machine call stack by peeking at the Perl call stack.

When calling Z_machine subroutines, we call z_call with all the information contained in a Z stack frame. We retrieve that information from the Perl call stack and build a Z-machine call stack with it.

restore_state

Implement the @restore opcode, restoring the current Z-machine state (as opposed to reading a table from a file, the other use of the @restore opcode)

IO::Interactive is a Perl module with utilities for interactive I/O.

SYNOPSIS

use IO::Interactive qw(is_interactive interactive busy);

if ( is_interactive() ) {
print "Running interactivelyn";
}

# or...

print {interactive} "Running interactivelyn";


$fh = busy {
do_noninteractive_stuff();
}

This module provides three utility subroutines that make it easier to develop interactive applications...

is_interactive()

This subroutine returns true if *ARGV and *STDOUT are connected to the terminal. The test is considerably more sophisticated than:

-t *ARGV && -t *STDOUT

as it takes into account the magic behaviour of *ARGV.

You can also pass is_interactive a writable filehandle, in which case it requires that filehandle be connected to a terminal (instead of *STDOUT). The usual suspect here is *STDERR:

if ( is_interactive(*STDERR) ) {
carp $warning;
}
interactive()

This subroutine returns *STDOUT if is_interactive is true. If is_interactive() is false, interactive returns a filehandle that does not print.

This makes it easy to create applications that print out only when the application is interactive:

print {interactive} "Please enter a value: ";
my $value = ;

You can also pass interactive a writable filehandle, in which case it writes to that filehandle if it is connected to a terminal (instead of writinbg to *STDOUT). Once again, the usual suspect is *STDERR:

print {interactive(*STDERR)} $warning;

busy {...}

This subroutine takes a block as its single argument and executes that block. Whilst the block is executed, *ARGV is temporarily replaced by a closed filehandle. That is, no input from *ARGV is possible in a busy block. Furthermore, any attempts to send input into the busy block through *ARGV is intercepted and a warning message is printed to *STDERR. The busy call returns a filehandle that contains the intercepted input.

A busy block is therefore useful to prevent attempts at input when the program is busy at some non-interactive task.

Tie::Form is a Perl module to access a machine readable database file that minics a hardcopy form.

SYNOPSIS

require Tie::Form;

#####
# Using support methods and file handle with
# the file subroutines such as open(), readline()
# print(), close()
#
tie *FORM_FILEHANDLE, Tie::Form, @options
$form = tied *FORM_FILEHANDLE;

#####
# Using support methods only, no file subroutines
#
$form = Tie::Form->new(@options);

$encoded_fields = $form->decode_record($record);
@fields = $form->decode_field($encoded_fields);

$encoded_fields = $form->encode_field (@fields);
$record = $form->encode_record($encoded_fields);

$record = $form->get_record();

####
# Subroutine interface
#
$encoded_fields = decode_record($record);
@fields = decode_field($encoded_fields);

$encoded_fields = encode_field (@fields);
$record = encode_record($encoded_fields);

If a subroutine or method will process a list of options, @options, that subroutine will also process an array reference, @options, [@options], or hash reference, %options, {@options}.

Time::Skew is a Perl module that computes local clock skew with respect to a remote clock.

SYNOPISI

use Time::Skew

# Init Convex Hull and timing data
my $hull=[];
my $result={};

# Iterate data point introduction
Time::Skew::convexhull($result,$datapoint,$hull);

This module supports the computation of the skew between two clocks: the (relative) skew is the speed with which two clocks diverge. For instance, if yesterday two clocks, at the same time, showed respectively 10:00 and 10:05, while today when the former shows 10:00 the latter shows 10:04, we say that their relative skew is 1 minute/24 hours, roughly 7E-4.

The module contains one single subroutine, which accepts as input a pair of timestamps, associated to a message from host A to host B: the timestamps correspond to the time when the message was sent, and to the time when message is received. Each timestamp reflects the value of the local clock where the operation takes place: the clock of host A for the send, the clock of B for the receive.

Please note that the module does _not_ contain any message exchange facility, but only the mathematics needed to perform the skew approximation, once timestamps are known.

The subroutine takes as argument:

a reference to a hash where values related to the timing of the network path from A to B;
a 2-elems array (a data point in the sequel) containing the timestamp of the receive event, and the differece between the send timestamp and the receive timestamp for one message;
a stack containing some data points, those that form the convex hull.

The usage is very simple, and is illustrated by the following example:

#!/usr/bin/perl -w
use strict;
use Time::Skew;

# Initialize data
my $hull=[];
my $result={};
while ( 1 ) {
# Exchange message and acquire a new data point
my $datapoint = acquire();
# Call the convexhull subroutine
Time::Skew::convexhull($result,$datapoint,$hull);
# After first message some results are still undefined
( defined $result->{skewjitter} ) || next;
# here you can use the results

};
}

The data returned in the "result" hash is the following:

result->{skew} the clock skew;
result->{skewjitter} the variance of the skew estimate, used to estimate convergence;
result->{jitter} difference between the current delay and the previous delay;
result->{delay} the communication delay, decremented by a constant (yet unknown) value, used to compute communication jitter;
result->{elems} the number of data points in the convex hull;
result->{select} the index of the data point in the convex hull used to compute the skew;
result->{itimestamp} the timestamp, first element in the data point just passed to the subroutine;
result->{delta} the timestamp difference, second element in the data point just passed to the subroutine;

The data returned in the "hull" stack is a series of data points, selected from those passed to successive calls of the subroutine. The number of data points in the "hull" stack usually does not exceed 20 units.

The algorithm is very fast: each call consists in scanning at most all data points in the "hull" stack, performing simple arithmetic operations for each element.

The algorithm must be fed with a sequence of data points before returning significant results. The accuracy of the estimate keeps growing while new data points are passed to the subroutine. A rough rule of thumb to evaluate estimate accuracy is to observe the skew jitter, and assume it corresponds to the skew estimate accuracy. Paths with quite regular communication delay (small jitter) converge faster.