Singleton Library Ready for Review

Recent changes: * The dependency lifetime now works by using the pointers themselves as dependencies, and using lazy creation to determine whether creation of the pointer or dereferencing of the pointer creates the instance. Using the pointer instead of a separate dependency class allows the lifetime to achieve a consistent interface with the other lifetime policies. * All lifetime policies now work uniformly for Singletons, Multitons, and potentially any Somethingtons that an end user might choose to implement (HashedMultiton, TwoKeyedMultiton, etc...). The only caveat is that the Multiton instance holder (a singleton used in the implementation of the multiton), must use a leaky lifetime. If any other type of lifetime is used, combining the longevity lifetime policy with the multiton ends up being disastrous. If the OS cleans up leaked memory when the program exits, this should not be a problem. Even so, I would like to find a better solution if possible. Because I have no experience with multi threading, I need someone to verify that I am locking in all of the right places, and that any singleton/multiton operations that need to be thread safe actually are thread safe. A sample test program is provided below, whose lifetime policies can be easily edited to verify order of creation and destruction in all circumstances. I am fairly confident that my singleton library is now complete. What are the next steps to take in adding it to Boost? -Jason // Sample Program #include <sstream> #include <fstream> #include "../Include/StaticAllocator.h" #include "../Include/MallocAllocator.h" #include "../Include/LongevityLifetime.h" #include "../Include/Singleton.h" #include "../Include/Multiton.h" using namespace boost::singleton; using std::stringstream; using std::ofstream; class TestLog : public Singleton < TestLog, LongevityLifetime < TestLog, 10 > > { private: ofstream out; protected: TestLog ( ) : out ( "log.dat" ) { out << "Test log created.\n"; } ~ TestLog ( ) { out << "Test log destroyed.\n"; out.close ( ); } public: void Write ( const char * msg ) { out << msg; } }; class A : public Multiton < int, A, LongevityLifetime < A, 5 > > { private: TestLog :: Pointer log; protected: A ( ) { log->Write ( "A created.\n" ); } ~ A ( ) { log->Write ( "A destroyed.\n" ); } }; // lifetime longevity higher than A, to verify that even though A is created first, it is still destroyed after B class B : public Singleton < B, LongevityLifetime < B, 7 > > { private: TestLog :: Pointer log; A :: Pointer a1; A :: Pointer a2; A :: Pointer a3; protected: B ( ) : a1 ( 0 ), a2 ( 1 ), a3 ( 1 ) { log->Write ( "B created.\n" ); } ~ B ( ) { log->Write ( "B destroyed.\n" ); } public: void foo ( ) { log->Write ( "foo called.\n" ); } }; int main ( ) { B::Pointer ptr; ptr->foo ( ); }

I forgot to mention, the new code is in the sandbox in the singleton folder, as before. http://boost-sandbox.sourceforge.net/vault/ -Jason

Jason Hise wrote:
I am fairly confident that my singleton library is now complete. What are the next steps to take in adding it to Boost?
Hi Jason, I have not been following the singleton discussion and have not examined your library, so for all I know your library may be ready for review now. However, it's only been about a month since you posted the initial version, and usually the process of refinement takes longer before a library is ready to be proposed for formal review. I would suggest that you let people start to use the library and give you more feedback before you propose it for review. Jonathan

Jonathan Turkanis wrote: I would suggest that you let people start to use the library
and give you more feedback before you propose it for review.
I second that and I just downloaded the library. That was motivated by frustration with my failures at attempting the simplest use of boost signals and boost function. I can not determine if I am having a stupid day, if documentation is really old, if examples are so contrieved and simple as to be useless, or whatever. So I would add a suggestion that people using/reviewing the code, as I will, post some nontrivial examples to be added to future documentation. Tony

Tony Juricic wrote:
Jonathan Turkanis wrote:
I would suggest that you let people start to use the library and give you more feedback before you propose it for review.
Thats reasonable... I was just really excited with the progress I have made in the design.
I second that and I just downloaded the library.
That was motivated by frustration with my failures at attempting the simplest use of boost signals and boost function. I can not determine if I am having a stupid day, if documentation is really old, if examples are so contrieved and simple as to be useless, or whatever.
So I would add a suggestion that people using/reviewing the code, as I will, post some nontrivial examples to be added to future documentation.
Should I start working on the documentation then? If so, what medium should I use? -Jason

Jason Hise wrote:
Should I start working on the documentation then? If so, what medium should I use?
IMO, considering the state of the rest of documentation, with few exceptions, any nontrivial examples are better than automated listing of details classes that you can't declare because it is understood that you shouldn't, and methods that you can't call. ;)

Jason Hise wrote:
Tony Juricic wrote:
Jonathan Turkanis wrote:
I would suggest that you let people start to use the library and give you more feedback before you propose it for review.
Thats reasonable... I was just really excited with the progress I have made in the design.
Quite understandable ;-)
So I would add a suggestion that people using/reviewing the code, as I will, post some nontrivial examples to be added to future documentation.
Should I start working on the documentation then? If so, what medium should I use?
Definitely. In some respects the documentation is more important than the code. See http://www.boost.org/more/writingdoc/index.html. You should probably consider using Boost.Book: http://www.boost.org/doc/html/boostbook.html Make sure the docs are complete enough that people can easily evaluate the design of the library. But also remember that the design may change, so trying to perfect the documention too soon could end up wasting some time.
-Jason
Best Regards, Jonathan

Jonathan Turkanis wrote:
Should I start working on the documentation then? If so, what medium should I use?
Definitely. In some respects the documentation is more important than the code.
See http://www.boost.org/more/writingdoc/index.html. You should probably consider using Boost.Book: http://www.boost.org/doc/html/boostbook.html
Make sure the docs are complete enough that people can easily evaluate the design of the library. But also remember that the design may change, so trying to perfect the documention too soon could end up wasting some time.
It looks like there would be a sharp learning curve involved in trying to use boostbook. Although I think that such documentation would eventually be great, I think that it would take too much time to put together now while people are trying to evaluate my library. Would a plain text tutorial be sufficient for the time being? -Jason

Jason Hise wrote:
Jonathan Turkanis wrote:
See http://www.boost.org/more/writingdoc/index.html. You should probably consider using Boost.Book: http://www.boost.org/doc/html/boostbook.html
It looks like there would be a sharp learning curve involved in trying to use boostbook. Although I think that such documentation would eventually be great, I think that it would take too much time to put together now while people are trying to evaluate my library. Would a plain text tutorial be sufficient for the time being?
I just said you should consider Boost Book. If you don't want to use it, no problem. Regarding plain text vs. html, I'd strongly recommend HTML. It doesn;t have to be anything fancy. Jonathan

Jason Hise wrote:
Jonathan Turkanis wrote:
Should I start working on the documentation then? If so, what medium should I use?
Definitely. In some respects the documentation is more important than the code.
See http://www.boost.org/more/writingdoc/index.html. You should probably consider using Boost.Book: http://www.boost.org/doc/html/boostbook.html
Make sure the docs are complete enough that people can easily evaluate the design of the library. But also remember that the design may change, so trying to perfect the documention too soon could end up wasting some time.
It looks like there would be a sharp learning curve involved in trying to use boostbook. Although I think that such documentation would eventually be great, I think that it would take too much time to put together now while people are trying to evaluate my library. Would a plain text tutorial be sufficient for the time being?
How about quickbook? It is now in the CVS tools directory. <<What is QuickBook?>> QuickBook is a WikiWiki style documentation tool geared towards C++ documentation using simple rules and markup for simple formatting tasks. QuickBook extends the WikiWiki concept. Like the WikiWiki, QuickBook documents are simple text files. A single QuickBook document can generate a fully linked set of nice HTML and PostScript/PDF documents complete with images and syntax-colorized source code. Features include: * generate BoostBook xml, to generate HTML, PostScript and PDF * simple markup to link to Doxygen-generated entities * macro system for simple text substitution * simple markup for italics, bold, preformatted, blurbs, code samples, tables, URLs, anchors, images, etc. * automatic syntax coloring of code samples * CSS support For point of reference, the entire set of xpressive's documentation at: http://boost-sandbox.sf.net/libs/xpressive was generated from a the single text file: http://tinyurl.com/6h464 (full link: http://cvs.sourceforge.net/viewcvs.py/*checkout*/boost-sandbox/boost-sandbox...) Up-to-date documentation for QuickBook can be found in CVS at boost/tools/quickbook/index.html . Cheers, -- Joel de Guzman http://www.boost-consulting.com http://spirit.sf.net

Joel de Guzman wrote:
How about quickbook? It is now in the CVS tools directory.
I think this is what I am going to go with. A couple questions: * In the example, where is the references section? I see a link to it at the beginning of the User's Guide section, but I can't find its actual definition. * When one makes a link to a function, class, header, etc..., where does that link actually send the person? How does one add the documentation for those specific items? -Jason

Tony Juricic wrote:
Jonathan Turkanis wrote: I would suggest that you let people start to use the library
and give you more feedback before you propose it for review.
I second that and I just downloaded the library.
That was motivated by frustration with my failures at attempting the simplest use of boost signals and boost function. I can not determine if I am having a stupid day, if documentation is really old, if examples are so contrieved and simple as to be useless, or whatever.
So I would add a suggestion that people using/reviewing the code, as I will, post some nontrivial examples to be added to future documentation.
I don't see the connection between the singleton library and function and signals. Jonathan

I would like to get general feedback on a feature that has been requested. Some background: Right now, my singleton pointer classes serve a variety of purposes. In the first place, they are the access mechanism for a singleton. Any pointer constructed immediately points to the singleton instance (or possibly null if the instance hasn't been created yet). If the singleton uses instant_creation, the first pointer created creates the singleton instance. When a member is accessed through a singleton pointer, an intermediate pointer type performs locking, and if lazy_creation is set it may also create the singleton instance. Regardless of the lifetime mechanism used, when the singleton instance gets destroyed all pointers instantly reflect this by becoming null. It has been suggested that I provide a mechanism to get a bald pointer to the instance, such as an unsafe_ptr member function of either the pointer class or the singleton itself. I feel that such a mechanism would be very dangerous, because the bald pointer could not perform lazy creation, it would not lock the operations, and it would not reflect when the singleton is destroyed. Are there instances in which allowing bald pointers to exist is necessary and/or useful? -Jason

A new version has been uploaded to the sandbox, although the former is still available. The new version implements many suggestions made by Pavel, including changing the naming conventions, file organization, and the addition of some pointer operations including an explicit create and destroy. -Jason
participants (5)
-
Jason Hise
-
Joel de Guzman
-
Jonathan Turkanis
-
Pavel Vozenilek
-
Tony Juricic