bslmt_timedcompletionguard

Detailed Description

Provide guard to verify work completion within a set duration.

Outline

• Purpose
• Classes
• Description
  • Usage
    • Example 1: Guarding Work on a Thread

Purpose

Provide guard to verify work completion within a set duration.

Classes

• bslmt::TimedCompletionGuard: guard to verify completion within a duration

Description

This component provides a thread-enabled guard, bslmt::TimedCompletionGuard, which invokes a handler displaying provided diagnostic text if the guard is not destroyed or released within a specified duration.

Usage

This section illustrates intended use of this component.

Example 1: Guarding Work on a Thread

In the following example a bslmt::TimedCompletionGuard is used as a testing aid verify work done on a thread completes in a specified amount of time. The work is done in two parts, but the actual tasks are not relevant to the example and is elided.

First, define the two thread functions containing the work to be done:

 /// Do some work based upon the specified `arg`.
 void *myWorkPart1(void *arg)
 {
 //  // do some stuff...
     (void)arg;
     return 0;
 }
 
 /// Do some other work based upon the specified `arg`.
 void *myWorkPart2(void *arg)
 {
     // do some other stuff...
     (void)arg;
     return 0;
 }

Next, we create and configure tcg to allow both parts of the work one second to complete and verify the guard was started successfully:

 bslmt::TimedCompletionGuard tcg;
 
 assert(0 == tcg.guard(bsls::TimeInterval(1, 0), "first part"));

Then, we create a thread to execute the first part of the work, and join the created thread when the work completes:

 {
     bslmt::ThreadUtil::Handle workerHandle;
 
     assert(0 == bslmt::ThreadUtil::create(&workerHandle, myWorkPart1, 0));
 
     bslmt::ThreadUtil::join(workerHandle);
 }

Next, we update the text displayed if the duration should expire to reflect the second portion of the work:

 tcg.updateText("second part");

Now, we use a thread to execute the second part of the work:

 {
     bslmt::ThreadUtil::Handle workerHandle;
 
     assert(0 == bslmt::ThreadUtil::create(&workerHandle, myWorkPart2, 0));
 
     bslmt::ThreadUtil::join(workerHandle);
 }

Finally, we release the guard:

 tcg.release();