Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Match(3)	      User Contributed Perl Documentation	      Match(3)

NAME
	Schedule::Match	- Handles and detects clash between pattern-based schedules

SYNOPSIS
	use Schedule::Match qw(scheck rcheck isleap uthash expand localtime);

	# hash structure of handled schedule
	$this =	{
	  life => 3600,	# how long each	execution of schedule lasts (in	second)
	  t_mh => '*',	# minute of the	hour	  - in crontab(5) format
	  t_hd => '*',	# hour of the day	  - in crontab(5) format
	  t_dw => '*',	# day of the week	  - in crontab(5) format
	  t_dm => '*',	# date of the month	  - in crontab(5) format
	  t_wm => '*',	# week of the month	  - in crontab(5) format
	  t_my => '*',	# month	of the year	  - in crontab(5) format
	  t_yt => '*',	# year (of the time)	  - in crontab(5) format
	  t_om => '*',	# occurrence in	the month - in crontab(5) format
	};

	# create hash structure	from given time
	$that =	uthash($time, $life);

	@when =	scheck($this, $that, ...); # list clash	(duration not considered)
	@when =	rcheck($this, $that, ...); # list clash	(duration     considered)

	$bool =	isleap($year);	       # check for leap	year
	@list =	expand($expr, \@fill); # expand	each crontab(5)	expression

	@time =	localtime($time);      # feature enhanced localtime(3)

DESCRIPTION
       This library allows you to manage schedule which	has structure similar
       to crontab(5) format. It	offers methods to detect clash between
       schedules (with or without duration considered),	and can	also tell
       when, and how often they	clash.

       From the	viewpoint of data structure, one major difference compared to
       crontab(5) is a concept of duration. Each schedule has its own
       duration, and clash detection can be done upon that.  For more
       information on data structure, please consult SCHEDULE STRUCTURE
       section below.

       All schedules are assumed to be in the same timezone. You will have to
       align them beforehand if	not.

       Currently available methods are as follows:

       @when = lcheck($this, $deep, $keep, $init, $last);
	   Returns list	of UNIX	times which is a time given schedule gets
	   invoked.

       @when = scheck($this, $that, $deep, $keep, $init, $last);
	   Detects clash between given schedules _without_ considering
	   duration. Returns the list of clash time (empty if not).  It	is
	   safe	to assume the list is sorted.

	   Options are:

	   - $deep
	       Sets the	"depth"	of clash detection. If set to false, it	will
	       report only one clash (first one) per day.

	   - $keep
	       Sets the	maximum	number of clashes to detect. Defaults to 1.

	   - $init
	       Set the starting	time of	timespan to do the detection.
	       Defaults	to the moment this method is called.

	   - $done
	       Set the closing time of timespan	to do the detection.  Defaults
	       to 3 years after	$init.

       $list = rcheck($exp0, $exp1, $deep, $keep, $init, $done);
	   Detects clash between given schedules _with_	duration considered.

	   This	is almost compatible with scheck except	that $deep and $keep
	   option does not work	as expected (for current implementation). For
	   $deep, it is	always set to 1, and for $keep,	you would need to
	   specify much	larger value (I	cannot give the	exact number since it
	   depends on how often	two schedules clash).

       $bool = isleap($year);
	   Returns wheather given year is leap year or not. Returns true if it
	   is, false otherwise.

       $hash = uthash($time[, $life]);
	   Create schedule structure from given	UNIX time. Optionally, you can
	   also	set the	duration of created schedule (which defaults to	0).

       @time = localtime($time);
	   Converts a time as returned by the time function to a 11-element
	   array with the time analyzed	for the	local time zone.

	   Except for appended 10th and	11th element, this is compatible with
	   built-in localtime.

	   Appended 2 elements (10th and 11th) are "week of the	month" and
	   "occurence in the month", both in 1-indexed style.

       @list = expand($expr, \@fill);
	   Function to expand given crontab(5)-like expression to the list of
	   matching values. \@fill is used to expand wildcard.

SCHEDULE STRUCTURE
       Below is	a structure of schedule	used in	this library:

	   life	=> duration of the schedule (in	second)
	   t_mh	=> minute of the hour
	   t_hd	=> hour	of the day
	   t_dm	=> day of the month
	   t_my	=> month of the	year
	   t_yt	=> year	(of the	time)
	   t_dw	=> day of the week
	   t_wm	=> week	of the month
	   t_om	=> occurrence in the month

       As you can see, this is a simple	hashtable. And for all t_* entries,
       crontab(5)-like notation	is supported. For this notation, please
       consult crontab(5) manpage.

       Next goes some examples.	To make	description short, I stripped the text
       "Schedule lasting for an	hour, starting from midnight" off from each
       description. Please assume that when reading.

       1. on every Jan.	1.
	       $schedule = {
		   life	=> 3600,
		   t_mh	=> '0',
		   t_hd	=> '0',
		   t_dm	=> '1',
		   t_my	=> '0',
		   t_yt	=> '*',
		   t_dw	=> '*',
		   t_wm	=> '*',
		   t_om	=> '*',
	       }

       2. on every 3rd Sunday.
	       $schedule = {
		   life	=> 3600,
		   t_mh	=> '0',
		   t_hd	=> '0',
		   t_dm	=> '*',
		   t_my	=> '*',
		   t_yt	=> '*',
		   t_dw	=> '0',
		   t_wm	=> '*',
		   t_om	=> '3',
	       }

       3. on Monday of every 3rd week.
	       $schedule = {
		   life	=> 3600,
		   t_mh	=> '0',
		   t_hd	=> '0',
		   t_dm	=> '*',
		   t_my	=> '*',
		   t_yt	=> '*',
		   t_dw	=> '1',
		   t_wm	=> '3',
		   t_om	=> '*',
	       }

       4. on every other day.
	       $schedule = {
		   life	=> 3600,
		   t_mh	=> '0',
		   t_hd	=> '0',
		   t_dm	=> '*/1',
		   t_my	=> '*',
		   t_yt	=> '*',
		   t_dw	=> '*',
		   t_wm	=> '*',
		   t_om	=> '*',
	       }

       5. on every other 2 days, from January to May.
	       $schedule = {
		   life	=> 3600,
		   t_mh	=> '0',
		   t_hd	=> '0',
		   t_dm	=> '*/2',
		   t_my	=> '0-4',
		   t_yt	=> '*',
		   t_dw	=> '*',
		   t_wm	=> '*',
		   t_om	=> '*',
	       }

       6. on the day which is Sunday _and_ the 1st day of the month.
	       $schedule = {
		   life	=> 3600,
		   t_mh	=> '0',
		   t_hd	=> '0',
		   t_dm	=> '1',
		   t_my	=> '*',
		   t_yt	=> '*',
		   t_dw	=> '0',
		   t_wm	=> '*',
		   t_om	=> '*',
	       }

       7. on Jan. 1, 1999
	       $schedule = {
		   life	=> 3600,
		   t_mh	=> '0',
		   t_hd	=> '0',
		   t_dm	=> '1',
		   t_my	=> '0',
		   t_yt	=> '1999',
		   t_dw	=> '*',
		   t_wm	=> '*',
		   t_om	=> '*',
	       }

	   Got the idea? You need to be	careful	on how you specify pattern,
	   since it is possible	to create pattern which	never happens (Say,
	   every Monday	of 1st week which is 3rd Monday	of the month).

	   Other key-value pair	can be in the hash, but	there is no gurantee
	   for those entries. It might clash with future enhancements to the
	   strcuture, or it might even be dropped when the internal copy of
	   the structure is made.

BUGS
       Two potential bugs are currently	known:

       UNIX-Y2K++ bug
	   Due to a feature of localtime(3), this cannot cannot	handle year
	   beyond 2038.	Since clash-detection code checks for the date in the
	   future, this	library	is likely to break before that (around 2030?).

       Clash detection bug
	   When	schedule(s) in question	repeat in very short time (like	every
	   minute), method rcheck might	not be able to check through timespan
	   that	is long	enough.

	   This	can be avoided if you specify HUGE value for $keep, but	then
	   things will be so slow, I believe it	is not practical.

COPYRIGHT
       Copyright 1999, Taisuke Yamada <tai@imasy.or.jp>.  All rights reserved.

       This library is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.

POD ERRORS
       Hey! The	above document had some	coding errors, which are explained
       below:

       Around line 432:
	   '=item' outside of any '=over'

       Around line 539:
	   You forgot a	'=back'	before '=head1'

perl v5.24.1			  2000-03-28			      Match(3)

NAME | SYNOPSIS | DESCRIPTION | SCHEDULE STRUCTURE | BUGS | COPYRIGHT | POD ERRORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Schedule::Match&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help