Singleton is documented!

The singleton library is finally documented! A complete tutorial in using the library along with an extensive reference section are provided. A tutorial on extending the library is forth-coming. The new zip is available in the <a href="http://boost-sandbox.sourceforge.net/vault/">sandbox</a> under the singleton folder, and should be extracted into the boost root directory. As always, suggestions are welcome. -Jason

An example source file which demonstrates how a zombie singleton might be implemented has been uploaded to the sandbox singleton directory for those interested. It will eventually be revised and become part of the upcoming tutorial on extending the singleton library, in a section about writing custom creators. A zombie singleton, if destroyed and re-created, is re-created as an empty shell with all no-op functions. Comments are welcome. -Jason

Jason Hise wrote:
An example source file which demonstrates how a zombie singleton might be implemented has been uploaded to the sandbox singleton directory for those interested. It will eventually be revised and become part of the upcoming tutorial on extending the singleton library, in a section about writing custom creators. A zombie singleton, if destroyed and re-created, is re-created as an empty shell with all no-op functions. Comments are welcome.
Jason, this is exactly what I'm looking for. Many thanks! Angus

Thanks to Michel Decima, the singleton library has been patched to work with g++ 3.4.3. The patched version is available for download in the sandbox. -Jason

Is there a specific formal way that I should be writing test programs for the singleton library? I was initially planning on just writing program results to a file and providing a second file containing expected output. However, because I am relatively new to boost I thought that there might be some bigger testing framework that I need to use. Is there? Additionally, I don't quite understand what bjam is, but everything seems to use it. Should I be using it as well, or does it only apply to libraries that need to be compiled? Singleton uses only header files. Thanks in advance for all replies. -Jason

"Jason Hise" <chaos@ezequal.com> wrote in message news:42264972.6040405@ezequal.com...
Is there a specific formal way that I should be writing test programs for the singleton library? I was initially planning on just writing program results to a file and providing a second file containing expected output. However, because I am relatively new to boost I thought that there might be some bigger testing framework that I need to use. Is there?
Additionally, I don't quite understand what bjam is, but everything seems to use it. Should I be using it as well, or does it only apply to libraries that need to be compiled? Singleton uses only header files.
Thanks in advance for all replies.
-Jason
You could use Boost.Test. It has several components. You may select the one that fit best to your habits/needs. Particularly Boost.Test tools includes output_test_stream that allows to match your output vs. pattern file. Check docs for more details. Gennadiy

Gennadiy Rozental wrote:
"Jason Hise" <chaos@ezequal.com> wrote in message news:42264972.6040405@ezequal.com...
Is there a specific formal way that I should be writing test programs for the singleton library? I was initially planning on just writing program results to a file and providing a second file containing expected output. However, because I am relatively new to boost I thought that there might be some bigger testing framework that I need to use. Is there?
Additionally, I don't quite understand what bjam is, but everything seems to use it. Should I be using it as well, or does it only apply to libraries that need to be compiled? Singleton uses only header files.
Thanks in advance for all replies.
-Jason
You could use Boost.Test. It has several components. You may select the one that fit best to your habits/needs. Particularly Boost.Test tools includes output_test_stream that allows to match your output vs. pattern file. Check docs for more details.
Gennadiy
It would appear that such tests are required to execute completely inside of a function block. Unfortunately, the very nature of a singleton makes this impossible. I need to be able to check the lifetimes of singletons with relation to each other, and with relation to static and global objects. This means I cannot even use cout to report results, as the standard streams could close up shop before the last of my singletons is destroyed. At the moment I am thinking that I will need to write two test programs... one to test the singletons and generate an output file, and one to verify the contents of the file that was generated. Does anyone see a simpler way? Also, I should ask what the policy is on testing classes that use a policy based design. How many different combinations of policies are expected to be tested? -Jason

Jason Hise wrote:
Gennadiy Rozental wrote:
Also, I should ask what the policy is on testing classes that use a policy based design. How many different combinations of policies are expected to be tested?
There is no policy that I know of. However, it's a good idea to test as many combinations as possible. I've written a Jamfile for policy_ptr which allows you to specify that a test will be run for a given list of policies. It could be modified for singleton so it would look something like this: CRETATION_TEST = policy1/policy3 policy5/policy2/policy3 policy6/policy9 ; test-suite "singleton" : [ singleton-run creation_test : $(CRETATION_TEST ) ] ... ; This would run the test createion_test.cpp once for each of the three combinations of policies in the list. I'll send it to you if you like. Jonathan

You could use Boost.Test. It has several components. You may select the one that fit best to your habits/needs. Particularly Boost.Test tools includes output_test_stream that allows to match your output vs. pattern file. Check docs for more details.
Gennadiy
It would appear that such tests are required to execute completely inside of a function block.
That not nesseserily true. I am not sure I fully understand you though
Unfortunately, the very nature of a singleton makes this impossible. I need to be able to check the lifetimes of singletons with relation to each other, and with relation to static and global objects.
Your design surely needs to cover function scope either (as any other scope), isn't it?
This means I cannot even use cout to report results, as the standard streams could close up shop before the last of my singletons is destroyed.
You may need to have separate program that specifically test that your library correctly deals with pre/post main processing, but majority of the logic should be testable on any scope.
At the moment I am thinking that I will need to write two test programs... one to test the singletons and generate an output file, and one to verify the contents of the file that was generated. Does anyone see a simpler way?
The second one could easily use Boost.Test. I am afraid thouhg you may have some difficulties integrating this solution with Boost.Build system
Also, I should ask what the policy is on testing classes that use a policy based design. How many different combinations of policies are expected to be tested?
You could use BOOST_TEST_CASE_TEMPLATE facility to test combinations based of mpl type sequences.
-Jason
Gennadiy

"Jonathan Turkanis" <technews@kangaroologic.com> wrote in message news:d06d1d$eqv$1@sea.gmane.org...
Gennadiy Rozental wrote:
You could use BOOST_TEST_CASE_TEMPLATE facility to test combinations based of mpl type sequences.
Could you point me to the docs for this facility?
Jonathan
This functionality present in 1.32.0. The semantics for this facility changes though. The best way to learn it would be to see how I use it for Boost.Test unit tests. Also check test_case_template_example in example directory. If you still have any question fell free to ask. I will update docs before release. Gennadiy

Gennadiy Rozental wrote:
You could use BOOST_TEST_CASE_TEMPLATE facility to test combinations
This functionality present in 1.32.0. The semantics for this facility changes though. The best way to learn it would be to see how I use it for Boost.Test unit tests. Also check test_case_template_example in example directory.
If you still have any question fell free to ask. I will update docs before release.
Okay, thanks. Jonathan

Gennadiy Rozental wrote:
You may need to have separate program that specifically test that your library correctly deals with pre/post main processing, but majority of the logic should be testable on any scope.
The thing is that the majority of the logic is in place just to handle the timing of automatic destruction. The actual act of creating and destroying is generally trivial by comparison. I suspect, though, that the biggest test of the library will be whether or not it compiles. If it compiles, it should almost certainly run correctly. -Jason

Gennadiy Rozental wrote:
You may need to have separate program that specifically test that your library correctly deals with pre/post main processing, but majority of
"Jason Hise" <chaos@ezequal.com> wrote in message news:4227814B.9020506@ezequal.com... the
logic should be testable on any scope.
The thing is that the majority of the logic is in place just to handle the timing of automatic destruction. The actual act of creating and destroying is generally trivial by comparison. I suspect, though, that the biggest test of the library will be whether or not it compiles. If it compiles, it should almost certainly run correctly.
-Jason
So you are saying that there is no way to initiate automatic destruction when leaving any given scope, only global scope? Gennadiy

Gennadiy Rozental wrote:
The thing is that the majority of the logic is in place just to handle the timing of automatic destruction. The actual act of creating and destroying is generally trivial by comparison. I suspect, though, that the biggest test of the library will be whether or not it compiles. If it compiles, it should almost certainly run correctly.
-Jason
So you are saying that there is no way to initiate automatic destruction when leaving any given scope, only global scope?
I believe some lifetime management policies rely on cleanup of local static variables or on atexit. Jonathan

Jonathan Turkanis wrote:
Gennadiy Rozental wrote:
The thing is that the majority of the logic is in place just to handle the timing of automatic destruction. The actual act of creating and destroying is generally trivial by comparison. I suspect, though, that the biggest test of the library will be whether or not it compiles. If it compiles, it should almost certainly run correctly.
-Jason
So you are saying that there is no way to initiate automatic destruction when leaving any given scope, only global scope?
I believe some lifetime management policies rely on cleanup of local static variables or on atexit.
Actually, I never use at_exit :D. It is indeed possible to trigger destruction early... the only problem is that that wouldn't be 'automatic' destruction, and as a result it really wouldn't test how the singleton would naturally behave. I need to be able to verify that if no explicit destruction is done by the user, the singleton still does clean itself up on its own, and that multiple singletons clean themselves up on their own in the correct order. -Jason

From: Jason Hise <chaos@ezequal.com>
It would appear that such tests are required to execute completely inside of a function block. Unfortunately, the very nature of a singleton makes this impossible. I need to be able to check the lifetimes of singletons with relation to each other, and with relation to static and global objects. This means I cannot even use cout to report results, as the standard streams could close up shop before the last of my singletons is destroyed.
They are supposed to survive however long your code needs them. How the implementation manages that is pure magic, as far as we know. It's just supposed to work. (27.3/2 plus footnote 265) -- Rob Stewart stewart@sig.com Software Engineer http://www.sig.com Susquehanna International Group, LLP using std::disclaimer;

Jason Hise wrote:
Is there a specific formal way that I should be writing test programs for the singleton library? I was initially planning on just writing program results to a file and providing a second file containing expected output. However, because I am relatively new to boost I thought that there might be some bigger testing framework that I need to use. Is there?
Boost.Test is the preferred/common thing thing to use.
Additionally, I don't quite understand what bjam is, but everything seems to use it.
That would be the program that interprets the Boost.Build files (Jamfile) :-)
Should I be using it as well, or does it only apply to libraries that need to be compiled? Singleton uses only header files.
If your are writing tests, which will be compiled, you have to use it as it's how we run the regression tests.
Thanks in advance for all replies.
If you need help with setting up Jamfiles we have a separate mail list for Boost.Build. -- -- Grafik - Don't Assume Anything -- Redshift Software, Inc. - http://redshift-software.com -- rrivera/acm.org - grafik/redshift-software.com - 102708583/icq
participants (6)
-
Angus Leeming
-
Gennadiy Rozental
-
Jason Hise
-
Jonathan Turkanis
-
Rene Rivera
-
Rob Stewart