{ "content": [ { "type": "text", "text": "# Class::Singleton (perldoc)\n\n## NAME\n\nClass::Singleton - Implementation of a \"Singleton\" class\n\n## SYNOPSIS\n\nuse Class::Singleton;\nmy $one = Class::Singleton->instance(); # returns a new instance\nmy $two = Class::Singleton->instance(); # returns same instance\n\n## DESCRIPTION\n\nThis is the \"Class::Singleton\" module. A Singleton describes an object class that can have only\none instance in any system. An example of a Singleton might be a print spooler or system\nregistry. This module implements a Singleton class from which other classes can be derived. By\nitself, the \"Class::Singleton\" module does very little other than manage the instantiation of a\nsingle object. In deriving a class from \"Class::Singleton\", your module will inherit the\nSingleton instantiation method and can implement whatever specific functionality is required.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION** (5 subsections)\n- **EXPORTS**\n- **KNOWN BUGS**\n- **FEEDBACK**\n- **AVAILABILITY**\n- **INSTALLATION**\n- **AUTHOR**\n- **COPYRIGHT**\n- **LICENCE**\n- **VERSION**\n- **DATE**\n- **HISTORY**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "Class::Singleton", "section": "", "mode": "perldoc", "summary": "Class::Singleton - Implementation of a \"Singleton\" class", "synopsis": "use Class::Singleton;\nmy $one = Class::Singleton->instance(); # returns a new instance\nmy $two = Class::Singleton->instance(); # returns same instance", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 5, "subsections": [] }, { "name": "DESCRIPTION", "lines": 10, "subsections": [ { "name": "Using the Class::Singleton Module", "lines": 20 }, { "name": "Deriving Singleton Classes", "lines": 110 }, { "name": "Methods", "lines": 1 }, { "name": "instance", "lines": 3 }, { "name": "has_instance", "lines": 24 } ] }, { "name": "EXPORTS", "lines": 2, "subsections": [] }, { "name": "KNOWN BUGS", "lines": 2, "subsections": [] }, { "name": "FEEDBACK", "lines": 20, "subsections": [] }, { "name": "AVAILABILITY", "lines": 12, "subsections": [] }, { "name": "INSTALLATION", "lines": 2, "subsections": [] }, { "name": "AUTHOR", "lines": 7, "subsections": [] }, { "name": "COPYRIGHT", "lines": 6, "subsections": [] }, { "name": "LICENCE", "lines": 4, "subsections": [] }, { "name": "VERSION", "lines": 2, "subsections": [] }, { "name": "DATE", "lines": 2, "subsections": [] }, { "name": "HISTORY", "lines": 2, "subsections": [] } ], "sections": { "NAME": { "content": "Class::Singleton - Implementation of a \"Singleton\" class\n", "subsections": [] }, "SYNOPSIS": { "content": "use Class::Singleton;\n\nmy $one = Class::Singleton->instance(); # returns a new instance\nmy $two = Class::Singleton->instance(); # returns same instance\n", "subsections": [] }, "DESCRIPTION": { "content": "This is the \"Class::Singleton\" module. A Singleton describes an object class that can have only\none instance in any system. An example of a Singleton might be a print spooler or system\nregistry. This module implements a Singleton class from which other classes can be derived. By\nitself, the \"Class::Singleton\" module does very little other than manage the instantiation of a\nsingle object. In deriving a class from \"Class::Singleton\", your module will inherit the\nSingleton instantiation method and can implement whatever specific functionality is required.\n\nFor a description and discussion of the Singleton class, see \"Design Patterns\", Gamma et al,\nAddison-Wesley, 1995, ISBN 0-201-63361-2.\n", "subsections": [ { "name": "Using the Class::Singleton Module", "content": "To import and use the \"Class::Singleton\" module the following line should appear in your Perl\nprogram:\n\nuse Class::Singleton;\n\nThe instance() method is used to create a new \"Class::Singleton\" instance, or return a reference\nto an existing instance. Using this method, it is only possible to have a single instance of the\nclass in any system.\n\nmy $highlander = Class::Singleton->instance();\n\nAssuming that no \"Class::Singleton\" object currently exists, this first call to instance() will\ncreate a new \"Class::Singleton\" and return a reference to it. Future invocations of instance()\nwill return the same reference.\n\nmy $macleod = Class::Singleton->instance();\n\nIn the above example, both $highlander and $macleod contain the same reference to a\n\"Class::Singleton\" instance. There can be only one.\n" }, { "name": "Deriving Singleton Classes", "content": "A module class may be derived from \"Class::Singleton\" and will inherit the instance() method\nthat correctly instantiates only one object.\n\npackage PrintSpooler;\nuse base 'Class::Singleton';\n\n# derived class specific code\nsub submitjob {\n...\n}\n\nsub canceljob {\n...\n}\n\nThe \"PrintSpooler\" class defined above could be used as follows:\n\nuse PrintSpooler;\n\nmy $spooler = PrintSpooler->instance();\n\n$spooler->submitjob(...);\n\nThe instance() method calls the newinstance() constructor method the first and only time a new\ninstance is created. All parameters passed to the instance() method are forwarded to\nnewinstance(). In the base class the newinstance() method returns a blessed reference to a\nhash array containing any arguments passed as either a hash reference or list of named\nparameters.\n\npackage MyConfig;\nuse base 'Class::Singleton';\n\nsub foo {\nshift->{ foo };\n}\n\nsub bar {\nshift->{ bar };\n}\n\npackage main;\n\n# either: hash reference of named parameters\nmy $config = MyConfig->instance({ foo => 10, bar => 20 });\n\n# or: list of named parameters\nmy $config = MyConfig->instance( foo => 10, bar => 20 );\n\nprint $config->foo(); # 10\nprint $config->bar(); # 20\n\nDerived classes may redefine the newinstance() method to provide more specific object\ninitialisation or change the underlying object type (to a list reference, for example).\n\npackage MyApp::Database;\nuse base 'Class::Singleton';\nuse DBI;\n\n# this only gets called the first time instance() is called\nsub newinstance {\nmy $class = shift;\nmy $self = bless { }, $class;\nmy $db = shift || \"myappdb\";\nmy $host = shift || \"localhost\";\n\n$self->{ DB } = DBI->connect(\"DBI:mSQL:$db:$host\")\n|| die \"Cannot connect to database: $DBI::errstr\";\n\n# any other initialisation...\n\nreturn $self;\n}\n\nThe above example might be used as follows:\n\nuse MyApp::Database;\n\n# first use - database gets initialised\nmy $database = MyApp::Database->instance();\n\nSome time later on in a module far, far away...\n\npackage MyApp::FooBar\nuse MyApp::Database;\n\n# this FooBar object needs access to the database; the Singleton\n# approach gives a nice wrapper around global variables.\n\nsub new {\nmy $class = shift;\nbless {\ndatabase => MyApp::Database->instance(),\n}, $class;\n}\n\nThe \"Class::Singleton\" instance() method uses a private hash to store a reference to any\nexisting instance of the object, keyed against the derived class package name.\n\nThis allows different classes to be derived from \"Class::Singleton\" that can co-exist in the\nsame system, while still allowing only one instance of any one class to exist. For example, it\nwould be possible to derive both '\"PrintSpooler\"' and '\"MyApp::Database\"' from\n\"Class::Singleton\" and have a single instance of *each* in a system, rather than a single\ninstance of *either*.\n\nYou can use the hasinstance() method to find out if a particular class already has an instance\ndefined. A reference to the instance is returned or \"undef\" if none is currently defined.\n\nmy $instance = MyApp::Database->hasinstance()\n|| warn \"No instance is defined yet\";\n" }, { "name": "Methods", "content": "" }, { "name": "instance", "content": "This method is called to return a current object instance or create a new one by calling\nnewinstance().\n" }, { "name": "has_instance", "content": "This method returns a reference to any existing instance or \"undef\" if none is defined.\n\nmy $testing = MySingleton1->hasinstance()\n|| warn \"No instance defined for MySingleton1\";\n\nnewinstance()\nThis \"private\" method is called by instance() to create a new object instance if one doesn't\nalready exist. It is not intended to be called directly (although there's nothing to stop\nyou from calling it if you're really determined to do so).\n\nIt creates a blessed hash reference containing any arguments passed to the method as either\na hash reference or list of named parameters.\n\n# either: hash reference of named parameters\nmy $example1 = MySingleton1->new({ pi => 3.14, e => 2.718 });\n\n# or: list of named parameters\nmy $example2 = MySingleton2->new( pi => 3.14, e => 2.718 );\n\nIt is important to remember that the instance() method will *only* call the\n*newinstance()* method once, so any arguments you pass may be silently ignored if an\ninstance already exists. You can use the hasinstance() method to determine if an instance\nis already defined.\n" } ] }, "EXPORTS": { "content": "*None*.\n", "subsections": [] }, "KNOWN BUGS": { "content": "*None*.\n", "subsections": [] }, "FEEDBACK": { "content": "Patches, bug reports, suggestions or any other feedback is welcome.\n\nPatches can be sent as GitHub pull requests at\n.\n\nBug reports and suggestions can be made on the CPAN Request Tracker at\n.\n\nCurrently active requests on the CPAN Request Tracker can be viewed at\n.\n\nPlease test this distribution. See CPAN Testers Reports at for\ndetails of how to get involved.\n\nPrevious test results on CPAN Testers Reports can be viewed at\n.\n\nPlease rate this distribution on CPAN Ratings at\n.\n", "subsections": [] }, "AVAILABILITY": { "content": "The latest version of this module is available from CPAN (see \"CPAN\" in perlmodlib for details)\nat\n\n or\n\n or\n\n.\n\nThe latest source code is available from GitHub at\n.\n", "subsections": [] }, "INSTALLATION": { "content": "See the INSTALL file.\n", "subsections": [] }, "AUTHOR": { "content": "Andy Wardley > .\n\nThanks to Andreas Koenig for providing some significant speedup patches and other ideas.\n\nSteve Hay > is now maintaining Class::Singleton as of\nversion 1.5.\n", "subsections": [] }, "COPYRIGHT": { "content": "Copyright (C) 1998 Canon Research Centre Europe Ltd.\n\nCopyright (C) 1998-2008 Andy Wardley. All rights reserved.\n\nCopyright (C) 2014, 2020 Steve Hay. All rights reserved.\n", "subsections": [] }, "LICENCE": { "content": "This module is free software; you can redistribute it and/or modify it under the same terms as\nPerl itself, i.e. under the terms of either the GNU General Public License or the Artistic\nLicense, as specified in the LICENCE file.\n", "subsections": [] }, "VERSION": { "content": "Version 1.6\n", "subsections": [] }, "DATE": { "content": "02 Dec 2020\n", "subsections": [] }, "HISTORY": { "content": "See the Changes file.\n", "subsections": [] } } } }