batchlas::WorkspaceLease Class Reference

Overview

A borrow of scratch memory from a Queue's workspace arena, returned to the arena when the handle goes out of scope.

auto ws = ctx.workspace(foo_buffer_size<B>(ctx, A));
foo<B>(ctx, A, ws.span());

Releasing a lease frees nothing (the memory belongs to the Queue), so the pointer stays valid for kernels still in flight; the bytes are handed to the next lease instead. On an in-order Queue that is safe by construction. On an out-of-order Queue, release() drains the queue first (see release()).

Leases nest, and the arena never moves leased memory. Release in reverse order of acquisition (scope-bound handles do this for free); an out-of-order release is safe but keeps its bytes reserved until every later lease is released, and debug builds assert on it.

Warning

Reassigning a live lease (ws = ctx.workspace(bigger);) acquires the new loan before the old one is returned, so a loop that reassigns every iteration ratchets the arena upward. Call ws.release() first.

Note

Tied to one Queue and not thread-safe, like Queue itself.

See also

Workspace

Definition at line 46 of file workspace.hh.

#include <batchlas/util/workspace.hh>

Constructors

WorkspaceLease() [1/3]

batchlas::WorkspaceLease::WorkspaceLease ( )

default

An empty lease that owns nothing.

WorkspaceLease() [2/3]

batchlas::WorkspaceLease::WorkspaceLease ( const WorkspaceLease & )

delete

WorkspaceLease() [3/3]

batchlas::WorkspaceLease::WorkspaceLease ( WorkspaceLease && other )

inlinenoexcept

Take over other's loan; other becomes empty.

Definition at line 54 of file workspace.hh.

~WorkspaceLease()

batchlas::WorkspaceLease::~WorkspaceLease ( )

inline

Returns the loan to the arena (see release()).

Definition at line 84 of file workspace.hh.

Functions

operator=() [1/2]

WorkspaceLease & batchlas::WorkspaceLease::operator= ( const WorkspaceLease & )

delete

operator=() [2/2]

WorkspaceLease & batchlas::WorkspaceLease::operator= ( WorkspaceLease && other )

inlinenoexcept

Release this lease's loan, then take over other's.

Definition at line 64 of file workspace.hh.

span() [1/2]

Span< std::byte > batchlas::WorkspaceLease::span

(

)

const &

The borrowed bytes.

Lvalue-only: the rvalue overload is deleted, because a span taken from a temporary lease is stale on the next line.

span() [2/2]

Span< std::byte > batchlas::WorkspaceLease::span ( ) const &&

delete

operator Span< std::byte >() [1/2]

batchlas::WorkspaceLease::operator Span< std::byte >

(

)

const &

Implicit conversion to the borrowed bytes; lvalue-only, as span().

operator Span< std::byte >() [2/2]

batchlas::WorkspaceLease::operator Span< std::byte > ( ) const &&

delete

data() [1/2]

std::byte * batchlas::WorkspaceLease::data ( ) const &

inline

Pointer to the borrowed bytes; lvalue-only, as span(). nullptr for an empty lease.

Definition at line 97 of file workspace.hh.

data() [2/2]

std::byte * batchlas::WorkspaceLease::data ( ) const &&

delete

size()

std::size_t batchlas::WorkspaceLease::size ( ) const

inline

Number of bytes borrowed.

Definition at line 100 of file workspace.hh.

release()

void batchlas::WorkspaceLease::release ( )

noexcept

Give the bytes back before the handle goes out of scope.

Idempotent and never throws, so it is safe from a destructor. Free on an in-order Queue. On an out-of-order Queue it blocks until the queue is idle when it actually hands bytes back (when this is the innermost live lease); an out-of-order return only marks the loan.

Warning

It waits only on the Queue the lease came from: it does not order against work submitted to a Queue derived from it (Queue(base, in_order)). Pass your own span for work on a sibling queue.