MCE::Sh...Sequence(3)

💅 NAME 💅

This is the MCE::Sh...Sequence(3) page from User Contributed Perl Documentation — yes, the title is literally truncated with ..., and we respect the drama 😭💀.

MCE::Shared::Sequence — Sequence helper class. It’s giving “tiny but important helper” energy 💖.

---

🎀 VERSION 🎀

This document describes MCE::Shared::Sequence version 1.893. Slay, versioned, periodt ✨.

---

🦋 DESCRIPTION 🦋

A number sequence class for use as a standalone or managed by MCE::Shared. So it can do its own solo main-character thing, or be managed by the shared vibe 🫶.

---

✨ SYNOPSIS ✨

Okay bestie, here’s the code exactly as it is — we do not touch the code, no cap 💅:

# 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 💖

🌟 new 🌟

Here are the construction signatures, bestie — all four of them, iconic and exact 🎀:

• 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). Literally boundaries-only behavior, and it ate 💅:

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. So you can set it up, rewind, and then go off 🔥:

# 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
);

🐆 next 🐆

Returns the next computed sequence(s). An undefined value is returned when the computed begin value exceeds the value held by end. That’s the signal to stop, bestie 🫶:

# 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 🧚

Signatures, because we keep every detail in the group chat:

• 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. Rewind is lowkey the reset button of the sequence world 💜:

$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 — the whole little crew 🫶✨.

---

👑 AUTHOR 👑

Mario E. Roy, <marioeroy AT gmail DOT com> — iconic author credit, no notes 👑.

---

Source/version/date tea at the very bottom: perl v5.40.0, 2024-09-10, MCE::Sh...Sequence(3) — that’s the footer, bestie, and we are so done 💅✨🎀