acquire<Y extends RType> static method

ScratchHandle<Y> acquire<Y extends RType>({ int? sizeInBytes, })

Claims the next scratch slot on the stack, allocating a new backing buffer if the stack has never reached this depth before.

By default the buffer is RaylibConfig.maxStructByteSize bytes. Pass sizeInBytes to request more; if the buffer already allocated at this depth is smaller than sizeInBytes, it is freed and reallocated at the larger size before being handed out, this permanently grows that depth's footprint for subsequent acquires, per the class-level note on the pool never shrinking. sizeInBytes must be positive if given.

The returned ScratchHandle owns exclusive access to its slot until ScratchHandle.release is called. Handles must be released in strict LIFO order, release the most recently acquired handle first, or ScratchHandle.release throws StateError.

Typical usage:

final a = MemoryScratch.acquire();
final b = MemoryScratch.acquire(sizeInBytes: 256);
try {
  // use a.pointer / b.pointer
} finally {
  b.release();
  a.release();
}

Implementation

static ScratchHandle<Y> acquire<Y extends RType>({int? sizeInBytes}) {
  if (sizeInBytes != null && sizeInBytes <= 0) {
    throw ArgumentError.value(sizeInBytes, 'sizeInBytes', 'must be positive');
  }
  final requiredSize = sizeInBytes ?? RaylibConfig.maxStructByteSize;

  if (_top == _buffers.length) {
    _buffers.add(.calloc(1, requiredSize));
    _sizes.add(requiredSize);
  } else if (_sizes[_top] < requiredSize) {
    _buffers[_top].free();
    _buffers[_top] = .calloc(1, requiredSize);
    _sizes[_top] = requiredSize;
  }

  final slot = _top++;
  return ScratchHandle._(slot, _buffers[slot].cast<Y>());
}