NAME

       oo::singleton - a class that does only allows one instance of itself

SYNOPSIS

       package require tcl::oo

       oo::singleton method ?arg ...?

CLASS HIERARCHY

       oo::object
          → oo::class
              → oo::singleton
________________________________________________________________________________________________________________

DESCRIPTION

       Singleton classes are classes that only permit at most one instance of themselves to exist. They unexport
       the  create and createWithNamespace methods entirely, and override the new method so that it only makes a
       new instance if there is no existing instance.  It is not recommended to inherit from a singleton  class;
       singleton-ness  is  not  inherited.  It  is not recommended that a singleton class's constructor take any
       arguments.

       Instances have their destroy method overridden with a method that always returns an  error  in  order  to
       discourage  destruction  of  the object, but destruction remains possible if strictly necessary (e.g., by
       destroying the class or using rename to delete it). They  also  have  a  (non-exported)  <cloned>  method
       defined  on them that similarly always returns errors to make attempts to use the singleton instance with
       oo::copy fail.

   CONSTRUCTOR
       The oo::singleton class does not define an explicit constructor; this means that it  is  effectively  the
       same as the constructor of the oo::class class.

   DESTRUCTOR
       The oo::singleton class does not define an explicit destructor; destroying an instance of it is just like
       destroying an ordinary class (and will destroy the singleton object).

   EXPORTED METHODS
       cls new ?arg ...?
              This  returns  the  current  instance  of  the  singleton  class, if one exists, and creates a new
              instance only if there is no existing instance. The additional arguments, arg ..., are  only  used
              if  a  new  instance  is actually manufactured; that construction is via the oo::class class's new
              method.

              This is an override of the behaviour of a superclass's method with an identical call signature  to
              the superclass's implementation.

   NON-EXPORTED METHODS
       The  oo::singleton  class  explicitly  states that create and createWithNamespace are unexported; callers
       should not assume that they have control over either the name or the  namespace  name  of  the  singleton
       instance.

EXAMPLE

       This  example  demonstrates  that  there  is only one instance even though the new method is called three
       times.

              oo::singleton create Highlander {
                  method say {} {
                      puts "there can be only one"
                  }
              }

              set h1 [Highlander new]
              set h2 [Highlander new]
              if {$h1 eq $h2} {
                  puts "equal objects"    → prints "equal objects"
              }
              set h3 [Highlander new]
              if {$h1 eq $h3} {
                  puts "equal objects"    → prints "equal objects"
              }

       Note that the name of the instance of the singleton is not guaranteed to be anything in particular.

SEE ALSO

       oo::class(3tcl)

KEYWORDS

       class, metaclass, object, single instance

TclOO                                                  0.3                                       singleton(3tcl)