/ 
Context-Vars-0.01
/ Context::Vars

NAME

Context::Vars - variables with context scope

VERSION

Version 0.01

SYNOPSIS

use Context::Vars q{$variable};

$variable = 'one';

sub change {
    $variable = 'two';
    print $variable;    # two
}

change();

print $variable;    # one

# A callback run later sees the values of the moment it was wrapped.
sub handle {
    my ($id) = @_;
    $variable = $id;
    return Context::Vars->wrap(sub { print "$variable\n" });
}

my $later = handle('request 42');
$later->();      # request 42

DESCRIPTION

A name given to use becomes a scalar in the calling package. Every package that imports the same name shares the one variable, and what it reads is the value in the context that is current at that moment.

An assignment to the variable holds until the sub it is written in returns, through any block in that sub and any way out of it, and is seen by every sub that sub calls. Code outside any sub keeps what it assigns for the program.

A callback wrapped with "wrap", or run with "run" in Context::Vars::Context, sees the values of the moment it was wrapped or captured, wherever and whenever it runs: from an event loop, after other work has changed them, or after other requests have come and gone.

LIMITS

  • Only scalars can be imported, with a plain name: $name.

  • No event loop captures for you. A callback sees its registering code's values only when it is wrapped; see "CALLBACKS AND LOOPS".

  • An assignment the module cannot see when the sub is compiled is not scoped to that sub. That is one made through @_, a for or grep alias, a symbolic reference, or a string eval inside a sub that makes no other assignment. It changes whatever context is current.

  • A variable can hold a reference to a hash, an array, code or an object, and the reference is its value: a sub's scope covers which reference the variable holds, not what that reference points at. A change made through it, $variable->{key} = 1, is seen by every context holding the same reference. To change a structure for one sub only, assign a changed copy: $variable = { %$variable, key => 1 }. Vivifying through a variable that is not set, $variable->{key} = 1 when it holds nothing, sets it in whatever context is current.

  • A sub that only assigns a variable for its caller changes nothing the caller can see: the assignment ends when that sub returns. Return the value and let the caller assign it.

CALLBACKS AND LOOPS

A callback that runs later, from an event loop, a queue or a future, sees the values of the moment it was registered only if whatever registered it captured them. "wrap" does that for one callback. A loop that does it for every callback it keeps is said to be wired.

A callback on a loop that is not wired runs outside any context. There a variable reads nothing, unless code outside any sub has assigned it, in which case it reads that value: never the value of the task that registered the callback.

ASYNC SUBS

Under Future::AsyncAwait, an async sub keeps its own variables across await: after the await it reads what it could see before it, and what it assigns is not seen by the code that resumed it. This needs nothing from Future::AsyncAwait to install, and works whichever of the two modules is loaded first.

METHODS

These are for code that runs other code later: an event loop, a queue, a future, a test. An application that only reads and assigns its variables does not need them.

capture

my $ctx = Context::Vars->capture;

Returns a Context::Vars::Context holding the values every variable has now. Later assignments, here or anywhere, do not change what it holds.

wrap

my $callback = Context::Vars->wrap(sub { ... });

Returns a code reference that calls the given one with the values every variable has now, wherever and whenever it is called. Its arguments are passed through and its return value is returned. Each call starts from those values afresh: nothing one call does is seen by the next.

current

my $ctx = Context::Vars->current;

Returns a Context::Vars::Context for the context code is running in now, rather than a copy of it. Code run in it with "run" in Context::Vars::Context and the code running now share their values.

C ABI

An event loop, a future or a queue written in C can capture the variables when a callback is registered and run the callback with them, and C code can read and assign a variable by name, with no Perl call in between. The header, context_vars_abi.h, is installed with this module and found through ExtUtils::Depends; it describes the table of functions, how to find it at run time, and the three calls a loop makes for each callback. A consumer needs that header and nothing else.

DEPENDENCIES

HAMT. Loading this module fails, with a message that says why, when HAMT is not installed or is too old.

AUTHOR

LNATION <email@lnation.org>

BUGS

Please report any bugs or feature requests to bug-context-vars at rt.cpan.org, or through the web interface at https://rt.cpan.org/NoAuth/ReportBug.html?Queue=Context-Vars.

LICENSE AND COPYRIGHT

This software is Copyright (c) 2026 by LNATION <email@lnation.org>.

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)