# ol.protocol53.deadline

Time budgets for protocol53 operations.

A deadline is a fixed point in the future that answers one question: has an
operation run out of time? Callers usually pass a positive
`java.time.Duration` under `:timeout`; the protocol53 facade converts it to
the `:deadline` in normalized provider options. Callers may instead create a
deadline when several operations must share one budget.

Deadlines are monotonic. They ride on `System/nanoTime`, so clock changes —
NTP corrections, daylight saving, someone setting the system clock — cannot
move them. That makes them reliable for timeouts and meaningless for anything
else: a deadline is just a number that only makes sense inside the process
that created it. Do not serialize it, store it, share it across processes, or
compare it against wall-clock time.

Build one with [`after`](#after). Check it with [`remaining`](#remaining), [`expired?`](#expired?), and
[`within?`](#within?).

## after

```clojure
(after duration)
```

Returns a deadline that falls `duration` from now.

`duration` is a positive `java.time.Duration`; it must be shorter than
`Long/MAX_VALUE` nanoseconds, roughly 292 years.

```clojure
(deadline/after (java.time.Duration/ofSeconds 30))
```

[source,window=_blank](https://github.com/outskirtslabs/protocol53/blob/docs/v0.0.1/api/src/main/ol/protocol53/deadline.clj#L42-L53)

---

## remaining

```clojure
(remaining operation-deadline)
```

Returns how much time is left before `operation-deadline`.

The value is a `java.time.Duration` that never goes negative; once the
deadline has passed it is `Duration/ZERO`.

[source,window=_blank](https://github.com/outskirtslabs/protocol53/blob/docs/v0.0.1/api/src/main/ol/protocol53/deadline.clj#L55-L67)

---

## expired?

```clojure
(expired? operation-deadline)
```

Returns `true` once `operation-deadline` has no time left.

[source,window=_blank](https://github.com/outskirtslabs/protocol53/blob/docs/v0.0.1/api/src/main/ol/protocol53/deadline.clj#L69-L72)

---

## within?

```clojure
(within? operation-deadline duration)
```

Returns `true` when `duration` still fits before `operation-deadline`.

Use it to decide whether to start work that needs at least `duration` of
budget. `duration` is a positive `java.time.Duration`.

[source,window=_blank](https://github.com/outskirtslabs/protocol53/blob/docs/v0.0.1/api/src/main/ol/protocol53/deadline.clj#L74-L81)