GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  SCHEDULE::MATCH (3)

.ds Aq ’

NAME



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



CONTENTS

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 <B>scheckB> 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 <B>localtimeB>.

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! <B>The above document had some coding errors, which are explained below:B>
Around line 432: ’=item’ outside of any ’=over’
Around line 539: You forgot a ’=back’ before ’=head1’
Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 MATCH (3) 2000-03-28

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.