txt: ## dist_cpan-ATROXAPER-Scheduler-DelayBetween.md
  [![Build Status](https://github.com/atroxaper/p6-Scheduler-DelayBetween/workflows/build/badge.svg)](https://github.com/atroxaper/p6-Scheduler-DelayBetween/actions)
  
  # NAME
  
  **Scheduler::DelayBetween** - Standard Scheduler's `cue` sub with the possibility to set a delay between each code execution.
  
  # SYNOPSIS
  
  ```
  use Scheduler::DelayBetween;
  
  my $cancel = cue({ say 'boom'; sleep 3; }, :5in, :1delay-between);
  sleep(5 + (3 + 1) * 13 + 0.7); # got 'boom' 14 times
  $cancel.cancel;
  
  ```
  
  # DESCRIPTION
  
  Sometimes you may need to execute some code several times with fixed delay *between* each execution. Standard Scheduler method `cue` does not provide such possibility. You can achieve it with this module.
  
  It provides a single subroutine:
  
  `cue(&code, :$at, :$in, :$every, :$times = 0, :&stop, :&catch, :$delay-between, :$scheduler = $*SCHEDULER --> Cancellation)`
  
  Parameters meaning:
  
  * `&code` - positional parameter - the code to run;
  * `:$at` or `:in` - `:$at` can be an Instant before which the code won't be run. Alternatively,`:$in` is the number of seconds (possibly fractional) to wait before running the code. If `:$at` is in the past or `:$in` is negative, the delay is treated as zero. Implementations may equate to zero very small values (e.g., lower than 0.001s) of `:$in` or result of `:$at - now`;
  * `:$times` - how many times the code has to be run. The parameter will be ignored if the value will be less than one. You can use this parameter together with `:&stop`, then the code will be run until at least one will stop it;
    `:&stop` - a check to decide should we continue to run the code. It will be called after each call of the code. Code running will stop if `:&stop` return `True`. You can use this parameter together with `:$times`, then the code will be run until at least one will stop it;
  * `:$scheduler` - a scheduler to de used for scheduling the code running;
  * `:&catch` - an exception handler, a sub with single positional parameter - exception occurred while the code running;
  * `:$delay-between` - delay in seconds (possibly fractional), which must pass between each run of the code except before the first one. If the parameter is missed, then the `cue` call will be delegated to the `cue` method of `:$scheduler`. Implementations may equate to zero very small values (e.g., lower than 0.001s).
  * `:$every` - will pass to the `cue` method of `:$scheduler` if you do not specify `:$delay-between` - you cannot use it together.
  
  The subroutine will return a `Cancellation` object you can use to cancel the future code runs.
  
  # AUTHOR
  
  Mikhail Khorkov [atroxaper@cpan.org](mailto:atroxaper@cpan.org)
  
  Source can be located at: [GitHub](https://github.com/atroxaper/p6-Scheduler-DelayBetween). Comments and Pull Requests
  are welcome.
  
  # COPYRIGHT AND LICENSE
  
  Copyright 2021 Mikhail Khorkov
  
  This library is free software; you can redistribute it and/or modify it under
  the Artistic License 2.0.
  