# `Continuum.Runtime.Lease`
[🔗](https://github.com/Yyeger/Continuum/blob/main/lib/continuum/runtime/lease.ex#L1)

Postgres lease acquisition and renewal for workflow runs.

The lease token is the fencing token used by the Postgres journal. Acquiring
a lease performs the roadmap's `UPDATE ... RETURNING` CAS: only unowned or
expired running runs can be claimed, and every successful claim receives a
fresh monotonic token from `continuum_lease_token_seq`.

# `t`

```elixir
@type t() :: %Continuum.Runtime.Lease{
  owner: binary(),
  run_id: binary(),
  token: integer()
}
```

# `acquire`

```elixir
@spec acquire(
  binary(),
  keyword()
) :: {:ok, t()} | {:error, term()}
```

Acquire a lease for a running or suspended run.

Returns `{:error, :not_acquired}` when another owner still holds the lease.

# `acquire!`

```elixir
@spec acquire!(
  binary(),
  keyword()
) :: t()
```

Acquire a lease or raise.

# `owner`

```elixir
@spec owner() :: binary()
```

Build the owner string used in lease rows.

# `owner`

# `renew`

```elixir
@spec renew(binary(), binary(), integer(), keyword()) ::
  :ok | {:ok, :cancel_requested} | {:error, :lost} | {:error, term()}
```

Renew a lease by owner and token.

Returns `{:error, :lost}` when the row is gone or the owner/token no longer
match, which means another process acquired the fencing token. Returns
`{:ok, :cancel_requested}` when the renewal succeeded but a durable cancel
request is pending on the run (set by `Continuum.cancel/2` when the owning
engine was unreachable).

---

*Consult [api-reference.md](api-reference.md) for complete listing*