ArenaExtension extension

Convenience extensions for binding native resources to an Arena.

This extension defines the scoped ownership model used throughout the library.

Any resource created or adopted through these helpers is owned by the arena and is automatically released when the arena is disposed.

The arena acts as a native lifetime boundary:

Memory allocated within the arena is freed together
COM interfaces have release called exactly once
Win32 string types are destroyed using their correct deallocator

This eliminates the need for manual cleanup and makes ownership explicit at the API boundary.

Prefer these helpers whenever you:

Allocate native memory
Create or acquire COM interfaces
Pass temporary strings to Win32 or COM APIs

Example:

using((arena) {
  final shell = arena.com<IShellItem>(ShellItem);
  final path  = arena.pcwstr(r'C:\Windows');

  // Native resources are safe to use within this scope.
});
// All associated native resources are released here.

If an object is created or adopted through this extension, its lifetime is exactly equal to the lifetime of the arena and must not be managed manually.

on

Arena

Methods

adopt<T extends IUnknown>(T object) → T: Available on Arena, provided by the ArenaExtension extension
Adopts an existing COM object into this Arena.
bstr(String string) → BSTR: Available on Arena, provided by the ArenaExtension extension
Creates a BSTR from a Dart string whose lifetime is bound to this Arena.
com<T extends IUnknown>(GUID clsid) → T: Available on Arena, provided by the ArenaExtension extension
Creates a new COM object and binds its lifetime to this Arena.
hstring(String string) → HSTRING: Available on Arena, provided by the ArenaExtension extension
Creates an HSTRING from a Dart string whose lifetime is bound to this Arena.
pcstr(String string) → PCSTR: Available on Arena, provided by the ArenaExtension extension
Creates a null-terminated ANSI string (PCSTR) from a Dart string whose lifetime is bound to this Arena.
pcwstr(String string) → PCWSTR: Available on Arena, provided by the ArenaExtension extension
Creates a null-terminated UTF-16 string (PCWSTR) from a Dart string whose lifetime is bound to this Arena.
pstr(String string) → PSTR: Available on Arena, provided by the ArenaExtension extension
Creates a null-terminated ANSI string (PSTR) from a Dart string whose lifetime is bound to this Arena.
pstrBuffer([int length = 1]) → PSTR: Available on Arena, provided by the ArenaExtension extension
Allocates a mutable ANSI string buffer (PSTR) with capacity for length characters, including the terminating NUL character.
pwstr(String string) → PWSTR: Available on Arena, provided by the ArenaExtension extension
Creates a null-terminated UTF-16 string (PWSTR) from a Dart string whose lifetime is bound to this Arena.
pwstrBuffer([int length = 1]) → PWSTR: Available on Arena, provided by the ArenaExtension extension
Allocates a mutable UTF-16 string buffer (PWSTR) with capacity for length UTF-16 code units, including the terminating NUL character.

ArenaExtension extension

Methods

win32 library