Data::SingletonManager - return/set/clear instances of singletons identified by keys in different namespaces.

Data-SingletonManager documentation Contained in the Data-SingletonManager distribution.

Index

Code Index:

NAME

Top

Data::SingletonManager - return/set/clear instances of singletons identified by keys in different namespaces.

SYNOPSIS

Top

  package My::Object;
  sub instance {
      my %args;
      ...
      my $key = "$args{userid}-$args{object_id}";
      return Data::SingletonManager->instance(
          namespace => __PACKAGE__,    # default; may omit.
          key => $key,
          creator => sub {
              return __PACKAGE__->new_instance($args{userid},
                                               $args{object_id});
          }
      );
  }

  package main;

  # return all singletons loaded in a namespace:
  @loaded_objs = Data::SingletonManager->instances("My::Object");

  # clear all singletons, in all packages (perhaps on new web request)
  Data::SingletonManager->clear_all;

  # clear all singletons in one namespace
  Data::SingletonManager->clear("My::Object");

DESCRIPTION

Top

This is a small utility class to help manage multiple keyed singletons in multiple namespaces. It is not a base class so you can drop it into any of your classes without namespace clashes with methods you might already have, like "new", "instance", "new_instance", etc.

PACKAGE METHODS

Top

All methods below are package methods. There are no instance methods.

instance(%args)

Package method to return (or create and save) a keyed instance where %args are:

"namespace"

defaults to the calling package

"key"

scalar key for instance. the (namespace, key) uniquely identifies an instance

"creator"

subref to return the instance if it doesn't already exist

instances([ $namespace ])

Return an array of all loaded instances in a namespace, which defaults to the calling namespace if no namespace is given.

clear([ $namespace ])

Clears all instances in a namespace, which defaults to the calling namespace if no namespace is given.

clear_all

Clears all instances in all namespaces.

AUTHORS

Top

Brad Fitzpatrick <brad@danga.com>

COPYRIGHT AND LICENSE

Top

Copyright 2005 by Six Apart, Ltd.

License is granted to use and distribute this module under the same terms as Perl itself.

Data-SingletonManager documentation Contained in the Data-SingletonManager distribution. 

############################################################################

package Data::SingletonManager;
use strict;
use Carp qw(croak);
use vars qw($VERSION);
$VERSION = "1.00";

my %data;  # namespace -> key -> value


sub instance {
    my $class = shift;

    my %args = @_;

    my $ns  = delete $args{namespace} || _calling_package();

    my $key = delete $args{key} or
	croak "Argument 'key' required.";

    my $creator = delete $args{creator} or
	croak "Argument 'creator' required.";
    
    croak "Unknown argument(s): " . join(", ", keys %args) if %args;

    # return instance if we have it, else set it
    return $data{$ns}{$key} ||= $creator->();
}

############################################################################


sub instances {
    my $class = shift;
    my $ns = shift || _calling_package();
    return () unless $data{$ns};
    return values %{ $data{$ns} };
}

############################################################################


sub clear {
    my $class = shift;
    my $ns = shift || _calling_package();
    delete $data{$ns};
}

############################################################################


sub clear_all {
    %data = ();
}


############################################################################
#   Utility methods
############################################################################

sub _calling_package {
    my $i = 0;
    while (my ($pkg) = caller($i++)) {
	next if $pkg eq __PACKAGE__;
	return $pkg;
    }
    die;
}

############################################################################


1;