SCOPE#

SCOPE(kind)#

Automatically runs code when a scope is exited (SCOPE(exit)), exited by means of an exception (SCOPE(fail)), or exited normally (SCOPE(success)).

The code controlled by SCOPE(exit) and SCOPE(fail) must not throw, otherwise the application will be terminated. The code controlled by SCOPE(exit) may throw.

SCOPE(exit) runs its code at the natural termination of the current scope. Example:

  // SCOPE(exit) runs the lambda upon the termination of the current scope.
  bool done = false;
  {
    SCOPE(exit)
    {
      done = true;
    };
    EXPECT(!done, "SCOPE_EXIT should not run early.");
  }
  EXPECT(done);

SCOPE(fail) runs its code if and only if the current scope is left by means of throwing an exception. Example:

  bool done = false;
  {
    SCOPE(fail)
    {
      done = true;
    };
    EXPECT(!done, "SCOPE_FAIL should not run early.");
  }
  assert(!done);

  try
  {
    SCOPE(fail)
    {
      done = true;
    };
    EXPECT(!done);
    throw 42;
  }
  catch (...)
  {
    EXPECT(done);
  }

Finally, SCOPE(success) runs its code if and only if the current scope is left by normal flow (as opposed to by an exception). Example:

  bool done = false;
  {
    SCOPE(success)
    {
      done = true;
    };
    EXPECT(!done);
  }
  EXPECT(done);
  done = false;

  try
  {
    SCOPE(success)
    {
      done = true;
    };
    EXPECT(!done);
    throw 42;
  }
  catch (...)
  {
    EXPECT(!done);
  }

If two or more SCOPE declarations are present in the same scope, they will take effect in the reverse order of their lexical order. Example:

  int counter = 0;
  {
    SCOPE(exit)
    {
      EXPECT(counter == 2);
      counter = 0;
    };
    SCOPE(success)
    {
      EXPECT(counter == 1);
      ++counter;
    };
    SCOPE(exit)
    {
      EXPECT(counter == 0);
      ++counter;
    };
    EXPECT(counter == 0);
  }
  EXPECT(counter == 0);