Let’s say you are implementing a class to represent a Phone. You might want to have the precondition that you cannot hangUp() a phone if it was already hung up.

The typical way to do this is with assert() statements, so in the file phone.cpp you might write:

88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106

class Phone
{
private:
   enum Status {
      Dialing,
      Connected,
      Disconnected
   };
   Status _status;
 
public:
   void hangUp()
   {
      assert(_status != Disconnected);
      /*... some code here...*/
   }
 
   /*... more functions here ...*/
};

Then let’s say in caller.cpp you are modeling someone who wants to have a “typical” phone conversation:

42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61

void Alice::callBob()
{
   _phone.dial("1-617-542-5942");
   friendlyGreetings();
   tellBruceSchneierJoke();
   haveSpecialDiscussion();
   _phone.HangUp();
}
 
void Alice::haveSpecialDiscussion()
{
   std::string password = askForThePassword();
   if (password == "hostilefork") {
      describeWorldTakeover();
      laughManiacally();
   } else {
      talkAboutTheWeather();
   }
   _phone.HangUp();
}

When callBob() executes and hits line 48, the Phone’s assertion will fire because it was already hung up during haveSpecialDiscussion() (on line 60). Most implementations of assert will capture the filename and line number where the actual assertion occurs, so you’d probably get a message like:

assertion failure on line 90 of phone.cpp

There’s no flexibility to let you indicate another “place” in the source. For instance, what if you wanted the assert to identify the precise offending call to hangUp()?

To address these kinds of needs I created codeplace. One of its many uses is the location-parameterized assert…which lets you pass in a “place” to be identified when the assert triggers. So in phone.cpp you would write:

98
99
100
101
102
103

public:
   void hangUp(const codeplace& cp)
   {
      assert(_status != Disconnected, cp);
      /*... some code here ...*/
   }

Then at the call sites, you would use a special macro called HERE to create a codeplace object which you pass as a parameter. For instance, the assertion-triggering call to hangUp() in caller.cpp would look like this:

48

_phone.hangUp(HERE(false));

(Note: the forthcoming documentation for codeplace will explain what false, true, and string parameters mean for “HERE” mean…)

Now when the assertion is reported by the program, it will identify the call site. With this change to our example above, you would get something more like:

assertion failure on line 48 of caller.cpp

The location-parameterized assert is only one application of a codeplace. They are helpful abstractions for any time we need to speak about a place in our source. For instance, if we wanted to track the previous disconnection call we could have a local variable in the Phone class to save it… and the tracked<T> template even does this for you automatically. There are some other nuances of the codeplace implementation that are beyond the scope of this particular issue.

You might theorize that run-time access to the stack is the ultimate API for dealing with this sort of thing. Imagine if Phone::hangUp() could somehow obtain an object representing the call stack, and then extract whatever information it wanted about the callers. That’s a little heavy-handed, and I believe that the odds of the API being abused are so high that a “narrower” protocol agreement between callers and subroutines would need to be established for the common scenarios.

Tags: cplusplus

This entry was posted on Sunday, May 1st, 2005 at 9:09 pm and is filed under C++. You can follow any responses to this entry through the RSS 2.0 feed. You can skip to the end and leave a response. Pinging is currently not allowed.