NAME

Global::Context - track the global execution context of your code

VERSION

version 0.003

OVERVIEW

WARNING! This code is very young and experimental. Its interface may change drastically as it is proven.

Global::Context is a system for tracking the context under which a program is currently running. It establishes a globally-accessible object that tracks the current user, authentication information, request originator, and execution stack.

This object can be replaced locally (within dynamic scopes) to affect pushes and pops against is stack, but is otherwise meant to be immutable once created.

  use Global::Context -all, '$Context';

  ctx_init({
    terminal => Global::Context::Terminal::Basic->new({ uri => 'ip://1.2.3.4' }),
    auth_token => Global::Context::AuthToken::Basic->new({
      uri   => 'websession://1234',
      agent => 'customer://abcdef',
    }),
  });

  sub eat_pie {
    my ($self) = @_;

    local $Context = ctx_push("eating pie");
    
    ...;
  }

  eat_pie;

Exports

If $Context is requested as an import, a package variable is added, aliasing a shared global. It can be localized as needed, affecting the global value. This feature is provided by Sub::Exporter::GlobExporter.

The shared globref is provided by the common_globref method, which can return a different globref in other subclasses to allow multiple global contexts to exist in one interpreter.

The ctx_init and ctx_push routines are exported by request or as part of the -all group.

ctx_init takes the same arguments as the constructor for the default context class (by default Global::Context::Env::Basic) and sets up the initial environment. If ctx_init is called after the environment has already been configured, it is fatal.

ctx_push takes either a stack frame (something that does Global::Context::StackFrame), the arguments to a construct a new Global::Context::StackFrame::Basic, or a stack frame description. It returns a new global context object, just like the current but with an extra stack frame. It's meant to be called like this:

  {
    local $Context = ctx_push("preferences subsystem");

    ...
  }

METHODS

common_globref

This returns the globref in which the context object is stored. This method can be replaced in subclasses to allow multiple global contexts to operate in one program.

default_context_class

default_frame_class

These methods name the default classes for new context objects and stack frames. They default to Global::Context::Env::Basic and Global::Context::StackFrame::Basic, by default.

AUTHOR

Ricardo Signes <rjbs@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2010 by Ricardo Signes.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.