Anonymous Thread Auto-Registration
Although using CfixCreateThread or CfixCreateSystemThread is the preferred way to create child threads, there may be situation where doing so is not possible.
Child threads not created using CfixCreateThread or CfixCreateSystemThread are referred to as Anonymous Threads.
By default, anonymous threads can make only very limited use of the cfix API and there is no explicit way to "promote" an anonymous thread to a fully-registered thread equivalent to a thread created using CfixCreateThread or CfixCreateSystemThread.
By enabling Anonymous Thread Auto-Registration, however, cfix can be instructed to automatically register anonymous threads. Although not equivalent to a fully-registered thread created using CfixCreateThread or CfixCreateSystemThread, such an auto-registered thread is then allowed to make use of the entire cfix API. In particular, any failed assertions or log messages will be properly handled by cfix.
Anonymous Thread Auto-Registration is not enabled by default -- rather, developers can opt-in to this behavior on a per-fixture basis by using the CFIX_FIXTURE_USES_ANONYMOUS_THREADS flag.
Example for an ordinary fixture declaration:
CFIX_BEGIN_FIXTURE( SomeFixture ) CFIX_FIXTURE_ENTRY( SomeTestCase ) CFIX_END_FIXTURE()
To enable Anonymous Thread Auto-Registration, this declaration has to be changed as follows (Note the usage of the _EX macro):
CFIX_BEGIN_FIXTURE_EX( SomeFixture, CFIX_FIXTURE_USES_ANONYMOUS_THREADS ) CFIX_FIXTURE_ENTRY( SomeTestCase ) CFIX_END_FIXTURE()
Once this change has been made, Anonymous Thread Auto-Registration is enabled for this specific fixture and any threads spawned by its tests will benefit from auto-registration.
Compared to the usage of CfixCreateThread or CfixCreateSystemThread, relying on auto-registration of anonymous threads suffers from the following limitations:
Unhandled Exceptions occuring on auto-registered child threads are not intercepted by cfix. This means that they are not reported and that they usually (unless a custom or unhandled exception filter is used) will lead to termination of the child thread.
An anonymous child thread is not auto-registered until an assertion has failed, CFIX_LOG has been called, or CfixRegisterThread has been called.
As a consequence of this, anonymous threads may not necessarily benefit from Auto Joining: Any anonymous thread that has not been auto-registered yet will not be waited for.
By explicitly calling CfixRegisterThread early in the child thread's lifecycle, developers can ensure that the thread will be regarded by Auto Joining. Note, however, that there is a potential race condition here: The enclosing test case may already have completed before the child thread is given the chance to call CfixRegisterThread.
The feature is only available for user mode code; kernel mode tests have to use CfixCreateSystemThread to create threads.