Thread...nitored(3pm)

📦
version 0.16 · 4 versions
, in debian trixie, ubuntu resolute, ubuntu stonking

💖 Thread::Conveyor::Monitored 💖

okay so this is the Thread...nitored(3pm) page from your User Contributed Perl Documentation — it's a Perl module, bestie, and it's so useful. Let's get into it 🎀

✨ NAME ✨

Thread::Conveyor::Monitored — monitor a belt for specific content 💅

✨ VERSION ✨

This documentation describes version 0.16. ⭐

✨ SYNOPSIS ✨

use Thread::Conveyor::Monitored;
my $mbelt = Thread::Conveyor::Monitored->new(
 {
  monitor => sub { print "monitoring value $_[0]\n" }, # is a must
  pre => sub { print "prepare monitoring\n" },         # optional
  post => sub { print "stop monitoring\n" },           # optional
  belt => $belt,   # use existing belt, create new if not specified
  exit => 'exit',  # defaults to undef

  checkpoint => sub { print "checkpointing\n" },
  frequency => 1000,

  optimize => 'memory', # optimization
  maxboxes => 50,       # specify throttling
  minboxes => 25,       # parameters
 }
);

$mbelt->put( "foo",['listref'],{'hashref'} );
$mbelt->put( undef ); # exit value by default
$mbelt->shutdown;

$mthread = $mbelt->thread;
$mtid = $mbelt->tid;

$belt = $mbelt->belt;

@post = $mthread->join; # optional, wait for monitor thread to end

$belt = Thread::Conveyor::Monitored->belt; # "pre", "do", "post"

✨ DESCRIPTION ✨

* A note of CAUTION * This module only functions on Perl versions 5.8.0 and later. And then only when threads are enabled with -Dusethreads. It is of no use with any version of Perl before 5.8.0 or without threads enabled. *

Okay so the Thread::Conveyor::Monitored module implements a single worker thread that takes boxes of values from a belt created with Thread::Conveyor, and it checks those boxes for specific content. 🧚

It's giving... a bunch of things, honestly:

  • simply logging actions that are placed on the belt, or
  • only spitting out warnings if a certain value shows up in a box, or
  • creating a safe sandbox for Perl modules that aren't thread-safe yet.

The action performed in the thread is determined by a name or a reference to a subroutine. That subroutine gets called for every box of values obtained from the belt. 💅

Any number of threads can safely put boxes with values and reference on the belt. No cap. 🫶

Optional checkpointing lets you check and save intermediate status. Iconic behaviour, fr fr.

✨ CLASS METHODS ✨

🌸 new 🌸

$mbelt = Thread::Conveyor::Monitored->new(
 {
  pre => \&pre,
  monitor => 'monitor',
  post => \&module::post,
  belt => $belt,   # use existing belt, create new if not specified
  exit => 'exit',  # defaults to undef

  checkpoint => \&checkpoint,
  frequency => 1000,

  optimize => 'memory',
  maxboxes => 50,
  minboxes => 25,
 },
 @parameters
);

The new function creates a monitoring function on an existing belt or on a new (empty) one. It returns the instantiated Thread::Conveyor::Monitored object. ✨

The first input parameter is a reference to a hash that should at least contain the monitor key with a subroutine reference.

The other input parameters are optional. If you specify them, they get passed to the pre routine, which is executed once when the monitoring is started.

The following field must be specified in the hash reference:

  • monitor — this is the mandatory one, bestie:
monitor => 'monitor_the_belt', # assume caller's namespace

or:

monitor => 'Package::monitor_the_belt',

or:

monitor => \&SomeOther::monitor_the_belt,

or:

monitor => sub {print "anonymous sub monitoring the belt\n"},

The monitor field specifies the subroutine to be executed for each set of values that is removed from the belt. It must be specified as either the name of a subroutine or as a reference to a (anonymous) subroutine.

The specified subroutine should expect the following parameters to be passed:

 1..N  set of values obtained from the box on the belt

What the subroutine does with the values is entirely up to the developer. 💫

The following fields are optional in the hash reference:

  • pre — the warm-up routine 🎀
pre => 'prepare_monitoring',           # assume caller's namespace

or:

pre => 'Package::prepare_monitoring',

or:

pre => \&SomeOther::prepare_monitoring,

or:

pre => sub {print "anonymous sub preparing the monitoring\n"},

The pre field specifies the subroutine to be executed once when the monitoring of the belt is started. It must be specified as either the name of a subroutine or as a reference to a (anonymous) subroutine.

The specified subroutine should expect the following parameters to be passed:

 1..N  any extra parameters that were passed with the call to L<new>.
  • post — the goodbye routine 🌸
post => 'stop_monitoring',             # assume caller's namespace

or:

post => 'Package::stop_monitoring',

or:

post => \&SomeOther::stop_monitoring,

or:

post => sub {print "anonymous sub when stopping the monitoring\n"},

The post field specifies the subroutine to be executed once when the monitoring of the belt is stopped. It must be specified as either the name of a subroutine or as a reference to a (anonymous) subroutine.

The specified subroutine should expect the following parameters to be passed:

 1..N  any parameters that were passed with the call to L<new>.

Any values returned by the post routine can be obtained with the join method on the thread object. 👑

  • belt — bring your own belt 🎀
belt => $belt,  # create new one if not specified

The belt field specifies the Thread::Conveyor object that should be monitored. A new Thread::Conveyor object will be created if it is not specified.

  • exit — the "we're done here" value 🦋
exit => 'exit',   # defaults to undef

The exit field specifies the value that will cause the monitoring thread to seize monitoring. The undef value will be assumed if it is not specified. This value should be put in a box on the belt to have the monitoring thread stop.

  • checkpoint — save your progress, bestie 💾
checkpoint => 'checkpointing',                 # assume caller's namespace

or:

checkpoint => 'Package::checkpointing',

or:

checkpoint => \&SomeOther::checkpointing,

or:

checkpoint => sub {print "anonymous sub to do checkpointing\n"},

The checkpoint field specifies the subroutine to be executed every time a checkpoint should be made (e.g. for saving or updating status). It must be specified as either the name of a subroutine or as a reference to a (anonymous) subroutine.

No checkpointing will occur by default. The frequency of checkpointing can be specified with the frequency field.

The specified subroutine should not expect any parameters to be passed. Any values returned by the checkpointing routine will be lost. 😭

  • frequency — how often we checkpoint 🎀
frequency => 100,                             # default = 1000

The frequency field specifies the number of boxes that should have been monitored before the checkpoint routine is called. If a checkpoint routine is specified but no frequency field is specified, then a frequency of 1000 will be assumed.

This field has no meaning if no checkpoint routine is specified with the checkpoint field. The default frequency can be changed with the frequency method.

  • optimize — cpu or memory, pick your vibe ⚡
optimize => 'cpu', # default: 'memory'

The optimize field specifies which implementation of the belt will be selected if there is no existing belt specified with the belt field. Currently there are two choices: 'cpu' and 'memory'. By default, the memory optimization will be selected if no specific optimization is specified.

You can call the class method optimize to change the default optimization.

  • maxboxes — throttling time 🚦
maxboxes => 50,

maxboxes => undef,  # disable throttling

The maxboxes field specifies the maximum number of boxes that can be sitting on the belt to be handled (throttling). If a new put would exceed this amount, putting of boxes will be halted until the number of boxes waiting to be handled has become at least as low as the amount specified with the minboxes field.

Fifty boxes will be assumed for the maxboxes field if it is not specified. If you do not want to have any throttling, you can specify the value undef for the field. But beware! If you do not have throttling active, you may wind up using excessive amounts of memory used for storing all of the boxes that have not been handled yet. 💀

The maxboxes method can be called to change the throttling settings during the lifetime of the object.

  • minboxes — the "okay go again" threshold 🌈
minboxes => 25, # default: maxboxes / 2

The minboxes field specified the minimum number of boxes that can be waiting on the belt to be handled before the putting of boxes is allowed again (throttling).

If throttling is active and the minboxes field is not specified, then half of the maxboxes value will be assumed.

The minboxes method can be called to change the throttling settings during the lifetime of the object.

🌸 belt 🌸

$belt = Thread::Conveyor::Monitored->belt; # only within "pre" and "do"

The class method belt returns the Thread::Conveyor::xxx object that this thread is monitoring. It is available within the pre and do subroutine only. 🫶

🌸 frequency 🌸

Thread::Conveyor::Monitored->frequency( 100 );

$frequency = Thread::Conveyor::Monitored->frequency;

The frequency class method allows you to specify the default frequency that will be used when a checkpoint routine is specified with the checkpoint field. The default frequency is set to 1000 if no other value has been previously specified. ✨

🌸 optimize 🌸

Thread::Conveyor::Monitored->optimize( 'cpu' );

$optimize = Thread::Conveyor::Monitored->optimize;

The optimize class method allows you to specify the default optimization type that will be used if no optimize field has been explicitly specified with a call to new. It returns the current default type of optimization. 💅

Currently two types of optimization can be selected:

  • memory — attempt to use as little memory as possible. Currently, this is achieved by starting a separate thread which hosts an unshared array. This uses the Thread::Conveyor::Thread sub-class.
  • cpu — attempt to use as little CPU as possible. Currently, this is achieved by using a shared array (using the Thread::Conveyor::Array sub-class), encapsulated in a hash reference if throttling is activated (then also using the Thread::Conveyor::Throttled sub-class).

okay bestie that's part 1, and there is SO much more coming — stay tuned 💖✨

💖 OBJECT METHODS 💖

Okay bestie, these are the moves you actually call on your monitored belt object. Periodt. ✨

✨ put ✨

$mbelt->put( $scalar,[],{} );
$mbelt->put( 'exit' ); # stop monitoring

The put method freezes all specified parameters in a box and puts it on the belt. The monitoring thread will stop monitoring if the exit value is put in the box. 👑

Please note that if you need to be very efficient, it may be worthwhile to extract the actual belt object first and use that to put boxes on the belt. The monitored put method is in fact only a gateway to the actual belt that is inside this object. iykyk.

✨ maxboxes ✨

$mbelt->maxboxes( 100 );
$maxboxes = $mbelt->maxboxes;

The maxboxes method returns the maximum number of boxes that can be on the belt before throttling sets in. The input value, if specified, specifies the new maximum number of boxes that may be on the belt. Throttling will be switched off if the value undef is specified. 🚦

Specifying the maxboxes field when creating the object with new is equivalent to calling this method.

The minboxes method can be called to specify the minimum number of boxes that must be on the belt before the putting of boxes is allowed again after reaching the maximum number of boxes. By default, half of the maxboxes value is assumed.

✨ minboxes ✨

$mbelt->minboxes( 50 );
$minboxes = $mbelt->minboxes;

The minboxes method returns the minimum number of boxes that must be on the belt before the putting of boxes is allowed again after reaching the maximum number of boxes. The input value, if specified, specifies the new minimum number of boxes that must be on the belt.

Specifying the minboxes field when creating the object with new is equivalent to calling this method.

The maxboxes method can be called to set the maximum number of boxes that may be on the belt before the putting of boxes will be halted.

✨ belt ✨

$belt = $mbelt->belt;

The belt instance method returns the Thread::Conveyor::xxx object that is being monitored. 🎀

✨ frequency ✨

$frequency = $mbelt->frequency;

The frequency instance method returns the frequency with which the checkpoint routine is being called. Returns undef if no checkpointing is being done.

✨ shutdown ✨

$mbelt->shutdown;

@from_monitor_thread = $mbelt->shutdown;

The shutdown method performs an orderly shutdown of the belt. It waits until all of the boxes on the belt have been removed before it returns.

Whatever was returned by the post routine of the monitoring thread, will also be returned by the shutdown method.

✨ thread ✨

$mthread = $mbelt->thread;

The thread method returns the thread object that is monitoring the contents of the belt.

✨ tid ✨

$tid = $mbelt->tid;

The tid method returns the thread id of the thread object that is monitoring the contents of the belt.

📦 REQUIRED MODULES 📦

  • load (any)
  • Thread::Conveyor (0.15)

⚡ OPTIMIZATIONS ⚡

This module uses load to reduce memory and CPU usage. This causes subroutines only to be compiled in a thread when they are actually needed at the expense of more CPU when they need to be compiled. Simple benchmarks however revealed that the overhead of the compiling single routines is not much more (and sometimes a lot less) than the overhead of cloning a Perl interpreter with a lot of subroutines pre-loaded. 🧚

⚠️ CAVEATS ⚠️

You cannot remove any boxes from the belt, as that is done by the monitoring thread. Therefore, the methods take, take_dontwait, peek and peek_dontwait are disabled on this object. 💀

Passing unshared values between threads is accomplished by serializing the specified values using Thread::Serialize. Please see the CAVEATS section there for an up-to-date status of what can be passed around between threads.

👑 AUTHOR 👑

Elizabeth Mattijsen, <liz@dijkmat.nl>.

Maintained by LNATION <email@lnation.org>

Please report bugs to <email@lnation.org>.

Copyright (c) 2002-2003, 2007, 2010 Elizabeth Mattijsen <liz@dijkmat.nl>. 2025 LNATION <email@lnation.org> All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

🔭 SEE ALSO 🔭

  • threads
  • threads::shared
  • Thread::Conveyor
  • Thread::Serialize
  • load

Source/version: perl v5.40.1 · Date: 2025-04-17 · Page: Thread...nitored(3pm) — k bye bestie, go monitor those belts! 💅✨

📦 where this page comes from