{ "content": [ { "type": "text", "text": "# IPC::Run::Timer (perldoc)\n\n## NAME\n\nIPC::Run::Timer -- Timer channels for IPC::Run.\n\n## SYNOPSIS\n\nuse IPC::Run qw( run timer timeout );\n## or IPC::Run::Timer ( timer timeout );\n## or IPC::Run::Timer ( :all );\n## A non-fatal timer:\n$t = timer( 5 ); # or...\n$t = IO::Run::Timer->new( 5 );\nrun $t, ...;\n## A timeout (which is a timer that dies on expiry):\n$t = timeout( 5 ); # or...\n$t = IO::Run::Timer->new( 5, exception => \"harness timed out\" );\n\n## DESCRIPTION\n\nThis class and module allows timers and timeouts to be created for use by IPC::Run. A timer\nsimply expires when it's time is up. A timeout is a timer that throws an exception when it\nexpires.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION** (2 subsections)\n- **SUBCLASSING**\n- **TODO**\n- **AUTHOR**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "IPC::Run::Timer", "section": "", "mode": "perldoc", "summary": "IPC::Run::Timer -- Timer channels for IPC::Run.", "synopsis": "use IPC::Run qw( run timer timeout );\n## or IPC::Run::Timer ( timer timeout );\n## or IPC::Run::Timer ( :all );\n## A non-fatal timer:\n$t = timer( 5 ); # or...\n$t = IO::Run::Timer->new( 5 );\nrun $t, ...;\n## A timeout (which is a timer that dies on expiry):\n$t = timeout( 5 ); # or...\n$t = IO::Run::Timer->new( 5, exception => \"harness timed out\" );", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 13, "subsections": [] }, { "name": "DESCRIPTION", "lines": 43, "subsections": [ { "name": "Time values", "lines": 17 }, { "name": "Interval fudging", "lines": 46 } ] }, { "name": "SUBCLASSING", "lines": 165, "subsections": [] }, { "name": "TODO", "lines": 4, "subsections": [] }, { "name": "AUTHOR", "lines": 2, "subsections": [] } ], "sections": { "NAME": { "content": "IPC::Run::Timer -- Timer channels for IPC::Run.\n", "subsections": [] }, "SYNOPSIS": { "content": "use IPC::Run qw( run timer timeout );\n## or IPC::Run::Timer ( timer timeout );\n## or IPC::Run::Timer ( :all );\n\n## A non-fatal timer:\n$t = timer( 5 ); # or...\n$t = IO::Run::Timer->new( 5 );\nrun $t, ...;\n\n## A timeout (which is a timer that dies on expiry):\n$t = timeout( 5 ); # or...\n$t = IO::Run::Timer->new( 5, exception => \"harness timed out\" );\n", "subsections": [] }, "DESCRIPTION": { "content": "This class and module allows timers and timeouts to be created for use by IPC::Run. A timer\nsimply expires when it's time is up. A timeout is a timer that throws an exception when it\nexpires.\n\nTimeouts are usually a bit simpler to use than timers: they throw an exception on expiration so\nyou don't need to check them:\n\n## Give @cmd 10 seconds to get started, then 5 seconds to respond\nmy $t = timeout( 10 );\n$h = start(\n\\@cmd, \\$in, \\$out,\n$t,\n);\npump $h until $out =~ /prompt/;\n\n$in = \"some stimulus\";\n$out = '';\n$t->time( 5 )\npump $h until $out =~ /expected response/;\n\nYou do need to check timers:\n\n## Give @cmd 10 seconds to get started, then 5 seconds to respond\nmy $t = timer( 10 );\n$h = start(\n\\@cmd, \\$in, \\$out,\n$t,\n);\npump $h until $t->isexpired || $out =~ /prompt/;\n\n$in = \"some stimulus\";\n$out = '';\n$t->time( 5 )\npump $h until $out =~ /expected response/ || $t->isexpired;\n\nTimers and timeouts that are reset get started by start() and pump(). Timers change state only\nin pump(). Since run() and finish() both call pump(), they act like pump() with respect to\ntimers.\n\nTimers and timeouts have three states: reset, running, and expired. Setting the timeout value\nresets the timer, as does calling the reset() method. The start() method starts (or restarts) a\ntimer with the most recently set time value, no matter what state it's in.\n", "subsections": [ { "name": "Time values", "content": "All time values are in seconds. Times may be any kind of perl number, e.g. as integer or\nfloating point seconds, optionally preceded by punctuation-separated days, hours, and minutes.\n\nExamples:\n\n1 1 second\n1.1 1.1 seconds\n60 60 seconds\n1:0 1 minute\n1:1 1 minute, 1 second\n1:90 2 minutes, 30 seconds\n1:2:3:4.5 1 day, 2 hours, 3 minutes, 4.5 seconds\n'inf' the infinity perl special number (the timer never finishes)\n\nAbsolute date/time strings are *not* accepted: year, month and day-of-month parsing is not\navailable (patches welcome :-).\n" }, { "name": "Interval fudging", "content": "When calculating an end time from a start time and an interval, IPC::Run::Timer instances add a\nlittle fudge factor. This is to ensure that no time will expire before the interval is up.\n\nFirst a little background. Time is sampled in discrete increments. We'll call the exact moment\nthat the reported time increments from one interval to the next a tick, and the interval between\nticks as the time period. Here's a diagram of three ticks and the periods between them:\n\n-0-0-0-0-0-0-0-0-0-0-1-1-1-1-1-1-1-1-1-1-2-...\n^ ^ ^\n|<--- period 0 ---->|<--- period 1 ---->|\n| | |\ntick 0 tick 1 tick 2\n\nTo see why the fudge factor is necessary, consider what would happen when a timer with an\ninterval of 1 second is started right at the end of period 0:\n\n-0-0-0-0-0-0-0-0-0-0-1-1-1-1-1-1-1-1-1-1-2-...\n^ ^ ^ ^\n| | | |\n| | | |\ntick 0 |tick 1 tick 2\n|\nstart $t\n\nAssuming that check() is called many times per period, then the timer is likely to expire just\nafter tick 1, since the time reported will have lept from the value '0' to the value '1':\n\n-0-0-0-0-0-0-0-0-0-0-1-1-1-1-1-1-1-1-1-1-2-...\n^ ^ ^ ^ ^\n| | | | |\n| | | | |\ntick 0 |tick 1| tick 2\n| |\nstart $t |\n|\ncheck $t\n\nAdding a fudge of '1' in this example means that the timer is guaranteed not to expire before\ntick 2.\n\nThe fudge is not added to an interval of '0'.\n\nThis means that intervals guarantee a minimum interval. Given that the process running perl may\nbe suspended for some period of time, or that it gets busy doing something time-consuming, there\nare no other guarantees on how long it will take a timer to expire.\n" } ] }, "SUBCLASSING": { "content": "INCOMPATIBLE CHANGE: Due to the awkwardness introduced by ripping pseudohashes out of Perl, this\nclass *no longer* uses the fields pragma.\n\nFUNCTIONS & METHODS\ntimer\nA constructor function (not method) of IPC::Run::Timer instances:\n\n$t = timer( 5 );\n$t = timer( 5, name => 'stall timer', debug => 1 );\n\n$t = timer;\n$t->interval( 5 );\n\nrun ..., $t;\nrun ..., $t = timer( 5 );\n\nThis convenience function is a shortened spelling of\n\nIPC::Run::Timer->new( ... );\n\n. It returns a timer in the reset state with a given interval.\n\nIf an exception is provided, it will be thrown when the timer notices that it has expired\n(in check()). The name is for debugging usage, if you plan on having multiple timers around.\nIf no name is provided, a name like \"timer #1\" will be provided.\n\ntimeout\nA constructor function (not method) of IPC::Run::Timer instances:\n\n$t = timeout( 5 );\n$t = timeout( 5, exception => \"kablooey\" );\n$t = timeout( 5, name => \"stall\", exception => \"kablooey\" );\n\n$t = timeout;\n$t->interval( 5 );\n\nrun ..., $t;\nrun ..., $t = timeout( 5 );\n\nA This convenience function is a shortened spelling of\n\nIPC::Run::Timer->new( exception => \"IPC::Run: timeout ...\", ... );\n\n. It returns a timer in the reset state that will throw an exception when it expires.\n\nTakes the same parameters as \"timer\", any exception passed in overrides the default\nexception.\n\nnew\nIPC::Run::Timer->new() ;\nIPC::Run::Timer->new( 5 ) ;\nIPC::Run::Timer->new( 5, exception => 'kablooey' ) ;\n\nConstructor. See \"timer\" for details.\n\ncheck\ncheck $t;\ncheck $t, $now;\n$t->check;\n\nChecks to see if a timer has expired since the last check. Has no effect on non-running\ntimers. This will throw an exception if one is defined.\n\nIPC::Run::pump() calls this routine for any timers in the harness.\n\nYou may pass in a version of now, which is useful in case you have it lying around or you\nwant to check several timers with a consistent concept of the current time.\n\nReturns the time left before endtime or 0 if endtime is no longer in the future or the\ntimer is not running (unless, of course, check() expire()s the timer and this results in an\nexception being thrown).\n\nReturns undef if the timer is not running on entry, 0 if check() expires it, and the time\nleft if it's left running.\n\ndebug\nSets/gets the current setting of the debugging flag for this timer. This has no effect if\ndebugging is not enabled for the current harness.\n\nendtime\n$et = $t->endtime;\n$et = endtime $t;\n\n$t->endtime( time + 10 );\n\nReturns the time when this timer will or did expire. Even if this time is in the past, the\ntimer may not be expired, since check() may not have been called yet.\n\nNote that this endtime is not starttime($t) + interval($t), since some small extra amount\nof time is added to make sure that the timer does not expire before interval() elapses. If\nthis were not so, then\n\nChanging endtime() while a timer is running will set the expiration time. Changing it while\nit is expired has no affect, since reset()ing a timer always clears the endtime().\n\nexception\n$x = $t->exception;\n$t->exception( $x );\n$t->exception( undef );\n\nSets/gets the exception to throw, if any. 'undef' means that no exception will be thrown.\nException does not need to be a scalar: you may ask that references be thrown.\n\ninterval\n$i = interval $t;\n$i = $t->interval;\n$t->interval( $i );\n\nSets the interval. Sets the end time based on the starttime() and the interval (and a\nlittle fudge) if the timer is running.\n\nexpire\nexpire $t;\n$t->expire;\n\nSets the state to expired (undef). Will throw an exception if one is defined and the timer\nwas not already expired. You can expire a reset timer without starting it.\n\nisrunning\nisreset\nisexpired\nname\nSets/gets this timer's name. The name is only used for debugging purposes so you can tell\nwhich freakin' timer is doing what.\n\nreset\nreset $t;\n$t->reset;\n\nResets the timer to the non-running, non-expired state and clears the endtime().\n\nstart\nstart $t;\n$t->start;\nstart $t, $interval;\nstart $t, $interval, $now;\n\nStarts or restarts a timer. This always sets the starttime. It sets the endtime based on\nthe interval if the timer is running or if no end time has been set.\n\nYou may pass an optional interval or current time value.\n\nNot passing a defined interval causes the previous interval setting to be re-used unless the\ntimer is reset and an endtime has been set (an exception is thrown if no interval has been\nset).\n\nNot passing a defined current time value causes the current time to be used.\n\nPassing a current time value is useful if you happen to have a time value lying around or if\nyou want to make sure that several timers are started with the same concept of start time.\nYou might even need to lie to an IPC::Run::Timer, occasionally.\n\nstarttime\nSets/gets the start time, in seconds since the epoch. Setting this manually is a bad idea,\nit's better to call \"start\"() at the correct time.\n\nstate\n$s = state $t;\n$t->state( $s );\n\nGet/Set the current state. Only use this if you really need to transfer the state to/from\nsome variable. Use \"expire\", \"start\", \"reset\", \"isexpired\", \"isrunning\", \"isreset\".\n\nNote: Setting the state to 'undef' to expire a timer will not throw an exception.\n", "subsections": [] }, "TODO": { "content": "use Time::HiRes; if it's present.\n\nAdd detection and parsing of [[[HH:]MM:]SS formatted times and intervals.\n", "subsections": [] }, "AUTHOR": { "content": "Barrie Slaymaker \n", "subsections": [] } } } }