# Scheduling Actions

Every driver can schedule events to occur in a number of different ways. Schedules are automatically cleared when a driver is terminated.

* Integer arguments are in milliseconds. `1000` == 1 second
* Strings can be used for a friendly representation of the time
  * `'30s'` == 30 seconds
  * `'5m'` == 5 minutes
  * `'1w2d3h5m'` == 1 week, 2 days, 3 hours and 5 minutes
  * `'2Y1M'` == 2 years, 1 month

| Function         | Arguments         | Description                                                                                                                                                                                                  |
| ---------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `schedule.in`    | String or Integer | schedule a task to run once in the time specified (formats above)                                                                                                                                            |
| `schedule.at`    | Time or String    | schedule a task at a time represented by a [Time object](http://ruby-doc.org/core-2.5.0/Time.html) or a parsable [time string](http://ruby-doc.org/stdlib-2.5.0/libdoc/date/rdoc/DateTime.html#parse-method) |
| `schedule.every` | String or Integer | schedule a task to run every time period on repeat                                                                                                                                                           |
| `schedule.cron`  | String            | A schedule that will fire based on a [CRON](https://en.wikipedia.org/wiki/Cron) string                                                                                                                       |
| `schedule.clear` |                   | shortcut for cancelling any active schedules                                                                                                                                                                 |

## Examples

```ruby
schedule.every('1m') do
    # perform some action, such as polling
end

schedule.in(500) do
    # ...
end

schedule.at(Time.now + 2.hours) do
    # ...
end

schedule.at('2018-02-02T15:32:41+11:00') do
    # ...
end

# Every day at 8am
schedule.cron('0 8 * * *') do
    # ...
end

# Canceling an individual schedule
@email_sched = schedule.in(500) do
    send_email
end
@email_sched.cancel
```

There are often situations where you want to run the block immediately.

```ruby
def connected
    schedule.every('1m', :run_now) do
        poll_current_state
    end
end
```

CRON also supports time zones - which should always be configured

```ruby
schedule.cron('0 8 * * *', timezone: 'Sydney') do
    # ...
end
```

See the list of supported [time zone strings](http://api.rubyonrails.org/classes/ActiveSupport/TimeZone.html) and information [about time zones](https://robots.thoughtbot.com/its-about-time-zones).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://engine.place.technology/developer-guide/drivers/scheduling.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.