Mirmon(3)

📦 version 2.11, in epel 10, epel 9, fedora 43, fedora 44

💖 Mirmon(3) 💖

okay bestie, welcome to Mirmon — it's the OO interface for mirmon objects, and honestly? she's iconic. this is the Perl-side API, manual section 3, and it's giving "I run the whole mirror-monitoring operation and I do it with style" 💅

✨ SYNOPSIS ✨

like, here's the vibe in code form:

use Mirmon ;

$m = Mirmon -> new ( [ $path-to-config ] )

$conf  = $m -> conf  ; # a Mirmon::Conf object
$state = $m -> state ; # the mirmon state

for my $url ( keys %$state )
  { $mirror = $state -> { $url } ; # a Mirmon::Mirror object
    $mail = $mirror -> mail ;      # contact address
    $mirror -> age ( time ) ;      # set mirror age
  }

and here's the part that makes everything else make sense — so many class and object methods are just there to get or set attributes:

$object -> attribute           # get an atttibute
$object -> attribute ( $attr ) # set an atttibute

that's the whole pattern. getter, setter, one shape. periodt. 🎀

👑 Mirmon class methods

new ( [$path] )

makes you a fresh Mirmon object, built from a config file it finds in $path — or, if you didn't pass one, from the default list of possible config files. the related objects (config, state) get created and initialised too. it's a whole little family 🫶

verbosity

okay so Mirmon always reports errors, no exceptions. normally she only reports the changes (inserts/deletes) she finds in the mirror_list. in quiet mode? nope, she doesn't. in verbose mode she reports progress: the startup and the finishing of probes. so chatty of her 💬

Mirmon::verbose ( [ $bool ] ) # get/set verbose
Mirmon::quiet   ( [ $bool ] ) # get/set quiet
Mirmon::debug   ( [ $bool ] ) # get/set debug

🦋 Mirmon object methods

  • conf — returns Mirmon's Mirmon::Conf object.
  • state — returns a hashref "{ url => mirror, ... }", where url is exactly as specified in the mirror list and mirror is a Mirmon::Mirror object.
  • regions — returns a hashref "{ country_code => country_name, ... }".
  • config_list — returns the list of default locations for config files.
  • get_dates ( $get [, $URL] ) — probes all the mirrors if $get is "all"; or a subset if $get is "update"; or only $URL if $get is "url".

🌸 Mirmon::Conf object methods

a Mirmon::Conf object represents a mirmon configuration. it's normaly created by Mirmon::new(). a specified (or default) config file gets read and interpreted. she reads, she interprets, she serves 💅

attribute methods

for every single config file entry, there is an attribute method — every one, no skips:

web_page, state, countries, mirror_list, probe, project_name, project_url, icons, project_logo, timeout, max_probes, min_poll, max_poll, min_sync, max_sync, list_style, put_histo, randomize, add_slash.

root

returns the file name of (the root of) the configuration file(s).

site_url

returns a hashref "{ site => url, ... }", as specified in the mirmon config file.

🧚 Mirmon::Mirror object methods

a Mirmon::Mirror object represents the last known state of a mirror. it's normaly created by Mirmon::new() from the state file, as specified in the mirmon config file. and yes — Mirmon::Mirror objects can be used to probe mirrors. main character energy fr fr 👑

attribute methods

  • url — the url as given in the mirror list.
  • age — the mirror's timestamp found by the last successful probe, or 'undef' if no probe was ever successful. 😭
  • last_status — the status of the last probe, or 'undef' if the mirror was never probed.
  • last_ok_probe — the timestamp of the last successful probe or 'undef' if the mirror was never successfully probed.
  • probe_history — the probe history is a list of 's' (for success) and 'f' (for failure) characters indicating the result of the probe. new results are appended whenever the mirror is probed.
  • state_history — the state history consists of a timestamp, a '-' char, and a list of chars indicating a past status: 's' (fresh), 'b' (oldish), 'f' (old), 'z' (bad) or 'x' (skip). the timestamp indicates when the state history was last updated. the current status of the mirror is determined by the mirror's age and a few configuration parameters (min_sync, max_sync, max_poll). the state history is updated when the mirror is probed. if the last update of the history was less than 24 hours ago, the last status is replaced by the current status. if the last update of the history was more than 24 hours ago, the current status is appended to the history. one or more 'skip's are inserted, if the timestamp is two or more days old (when mirmon hasn't run for more than two days).
  • last_probe — the timestamp of the last probe, or 'undef' if the mirror was never probed.

object methods

  • mirmon — returns the parent Mirmon object.
  • state_history_time — returns the time part of the state_history attribute.
  • state_history_hist — returns the history part of the state_history attribute.
  • type, site, home — for an url like ftp://www.some.org/path/to/home, the type is ftp, the site is www.some.org, and home is ftp://www.some.org/.
  • age_in_days — returns the mirror's age (in fractional days), based on the mirror's timestamp as found by the last successful probe ; or based on the length of the state history if no probe was ever successful. returns 'undef' if the mirror was never probed.
  • mail — returns the mirror's contact address as specified in the mirror list.
  • region — returns the mirror's country code as specified in the mirror list.
  • start_probe — start a probe for the mirror in non-blocking mode ; returns the associated (IO::Handle) file handle. the caller must maintain an association between the handles and the mirror objects. no pressure bestie 🫶
  • finish_probe ( $handle ) — sets the (IO::Handle) $handle to blocking IO ; reads a result from the handle, and updates the state of the mirror.

🌈 SEE ALSO 🌈

💜 AUTHOR 💜

 (c) 2003-2016 Henk P. Penning
 Faculty of Science, Utrecht University
 http://www.staff.science.uu.nl/~penni101/ -- penning@uu.nl
 mirmon-2.11 - Sat Jul 23 09:12:31 2016 ; henkp

okay that's the whole page 🍓 and for the sign-off: this gorgeous thing is Mirmon(3) from perl v5.8.8, dated 2016-07-23. she ate and left no crumbs. bye bestie, go probe something 💖✨🦋

📦 where this page comes from