NAME

MCE::Shared::Sequence - Sequence helper class

VERSION

This document describes MCE::Shared::Sequence version 1.876

DESCRIPTION

A number sequence class for use as a standalone or managed by MCE::Shared.

SYNOPSIS

 # non-shared or local construction for use by a single process

 use MCE::Shared::Sequence;

 my $seq_a = MCE::Shared::Sequence->new( $begin, $end, $step, $fmt );

 my $seq_b = MCE::Shared::Sequence->new(
    { chunk_size => 10, bounds_only => 1 },
    $begin, $end, $step, $fmt
 );

 # construction for sharing with other threads and processes

 use MCE::Shared;

 my $seq_a = MCE::Shared->sequence( 1, 100 );

 my $seq_b = MCE::Shared->sequence(
    { chunk_size => 10, bounds_only => 1 },
    1, 100
 );

 # example

 use MCE::Hobo;

 sub parallel_a {
    my ( $id ) = @_;
    while ( defined ( my $num = $seq_a->next ) ) {
       print "$id: $num\n";
    }
 }

 sub parallel_b {
    my ( $id ) = @_;
    while ( my ( $beg, $end ) = $seq_b->next ) {
       for my $num ( $beg .. $end ) {
          print "$id: $num\n";
       }
    }
 }

 MCE::Hobo->new( \&parallel_a, $_ ) for 1 .. 2;
 MCE::Hobo->new( \&parallel_b, $_ ) for 3 .. 4;

 # ... do other work ...

 MCE::Hobo->waitall();

API DOCUMENTATION

MCE::Shared::Sequence->new ( { options }, begin, end [, step, format ] )

MCE::Shared::Sequence->new ( begin, end [, step, format ] )

MCE::Shared->sequence ( { options }, begin, end [, step, format ] )

MCE::Shared->sequence ( begin, end [, step, format ] )

Constructs a new object. "step", if omitted, defaults to 1 if "begin" is smaller than "end" or "-1" if "begin" is greater than "end". The "format" string is passed to "sprintf" behind the scene (% may be omitted).

 $seq_n_formatted = sprintf( "%4.1f", $seq_n );

Two options "chunk_size" and "bounds_only" are supported, which default to 1 and 0 respectively. Chunking reduces the number of IPC calls to and from the shared-manager process for large sequences.

If "bounds_only => 1" is specified, the "next" method computes the "begin" and "end" values only for the chunk and not the numbers in between (hence boundaries only).

 use MCE::Shared;

 # demo 1

 $seq1 = MCE::Shared->sequence(
    { chunk_size => 10, bounds_only => 0 }, 1, 20
 );

 # @chunk = $seq1->next;  # ( qw/  1  2  3  4  5  6  7  8  9 10 / )
 # @chunk = $seq1->next;  # ( qw/ 11 12 13 14 15 16 17 18 19 20 / )

 while ( my @chunk = $seq1->next ) {
    ...
 }

 # demo 2

 $seq2 = MCE::Shared->sequence(
    { chunk_size => 10, bounds_only => 1 }, 1, 100
 );

 # ( $beg, $end ) = $seq2->next;  # (  1,  10 )
 # ( $beg, $end ) = $seq2->next;  # ( 11,  20 )
 # ( $beg, $end ) = $seq2->next;  # ( 21,  30 )
 #    ...
 # ( $beg, $end ) = $seq2->next;  # ( 81,  90 )
 # ( $beg, $end ) = $seq2->next;  # ( 91, 100 )

 # The optional chunk_id value, starting at 1, applies to sequence
 # objects configured with the bounds_only option set to a true
 # value. API available since 1.834.

 while ( my ( $beg, $end, $chunk_id ) = $seq2->next ) {
    for my $i ( $beg .. $end ) {
       ...
    }
 }

Parameters may be given later with "rewind" before calling "next".

 # non-shared or local construction for use by a single process

 use MCE::Shared::Sequence;

 $seq = MCE::Shared::Sequence->new;
 $seq->rewind( -1, 1, 0.1, "%4.1f" );

 $seq = MCE::Shared::Sequence->new(
    { chunk_size => 10, bounds_only => 1 }, 1, 100
 );

 # construction for sharing with other threads and processes

 use MCE::Shared;

 $seq = MCE::Shared->sequence;
 $seq->rewind( 1, 100 );

 $seq = MCE::Shared->sequence(
    { chunk_size => 10, bounds_only => 1 }, 1, 100
 );

Returns the next computed sequence(s). An undefined value is returned when the computed "begin" value exceeds the value held by "end".

 # default: { chunk_size => 1, bounds_only => 0 }
 $seq = MCE::Shared->sequence( 1, 100 );

 while ( defined ( my $num = $seq->next ) ) {
    ...
 }

 # chunking

 $seq = MCE::Shared->sequence(
    { chunk_size => 10 }, 1, 100
 );

 while ( my @chunk = $seq->next ) {
    ...
 }

 # chunking, boundaries only

 $seq = MCE::Shared->sequence(
    { chunk_size => 10, bounds_only => 1 }, 1, 100
 );

 while ( my ( $beg, $end, $chunk_id ) = $seq->next ) {
    for my $i ( $beg .. $end ) {
       ...
    }
 }

rewind ( { options }, begin, end [, step, format ] )

rewind ( begin, end [, step, format ] )

Sets the initial value back to the value held by "begin" when no arguments are given. Otherwise, resets the sequence with given criteria.

 $seq->rewind;

 $seq->rewind( { chunk_size => 10, bounds_only => 1 }, 1, 100 );

 while ( my ( $beg, $end ) = $seq->next ) {
    for my $i ( $beg .. $end ) {
       ...
    }
 }

 $seq->rewind( 1, 100 );

 while ( defined ( my $num = $seq->next ) ) {
    ...
 }

INDEX

MCE, MCE::Hobo, MCE::Shared

AUTHOR

Mario E. Roy, <marioeroy AT gmail DOT com>