class WidgetFactory
   {
private:
   // a really, really slow routine
   void StopProcessesSoItsSafeToMakeWidgets();
 
   // another really, really slow routine
   void RestartProcesses();
 
public:
   Widget* MakeAWidget()
      {
      StopProcessesSoItsSafeToMakeWidgets();
      Widget* w = new Widget();
      RestartProcesses();
      return w;
      }
 
   std::vector<Widget*> MakeManyWidgets(int HowMany)
      {
      std::vector<Widget*> ret;
      StopProcessesSoItsSafeToMakeWidgets();
      for (int temp = 0; temp < HowMany; temp++)
          ret.push_back(new Widget());
      RestartProcesses();
      return ret;
      }
 
   void DoSomethingElse()
      {
      assert(ProcessesRunning());
      return;
      }
   };

class WidgetFactory
   {
private:
   mutable int widgets_hint;
 
private:
   // a really, really slow routine
   void StopProcessesSoItsSafeToMakeWidgets();
 
   // another really, really slow routine
   void RestartProcesses();
 
public:
   void HINT_MakingManyWidgets(int HowMany) const
      {
      widgets_hint += HowMany;
      }
 
   Widget* MakeAWidget()
      {
      if (ProcessesRunning())
         StopProcessesSoItsSafeToMakeWidgets();
      Widget* w = new Widget();
      if (widgets_hint > 0)
         {
         widgets_hint--;
         RestartProcesses();
         }
      return w;
      }
 
   void DoSomethingElse()
      {
      if (!ProcessesRunning())
         {
         widgets_hint = 0;
         RestartProcesses();
         }
      }
   };

3 Responses to “Cleaner API Design Using Ignorable “Hints””

1. Jeremy Friesner Says:
   January 2nd, 2009 at 3:08 pm

   Hi Brian,

   I do something similar, but perhaps a little bit better. My version of the API would look like this:

   [code]
   […]

   public:
   void BeginMakingWidgetsBatch()
   {
   widgets_batch_count++;
   }

   Widget * MakeAWidget()
   {
   if (ProcessesRunning())
   StopProcessesSoItsSafeToMakeWidgets();

   Widget * w = new Widget();

   if (widgets_batch_count == 0)
   RestartProcesses();

   return w;
   }

   void EndMakingWidgetsBatch()
   {
   if (–widgets_batch_count == 0)
   RestartProcesses();
   }
   [/code]

   I think this is better, because it doesn’t force the caller to try and predict in advance how many widgets he is planning to make. If he wants “better performance mode”, he simply does this:

   [code]
   BeginMakingWidgetsBatch();
   // however many calls to MakeAWidget() he cares to do, go here
   EndMakingWidgetsBatch();
   [/code]

   … and it handles nested calls correctly as well. The processes are always restored at the last call to EndMakingWidgetsBatch(). And of course the non-batch version does the right thing as well.

   The only hazard here would be the possibility that the user will call BeginMakingWidgetsBatch() and forget to call a matching EndMakingWidgetsBatch(), in which case your processes would never get restarted. So if you wanted to be extra safe/fancy, you could preclude that possibility by putting those calls into the constructor and destructor of an object that the user puts on the stack, instead:

   [code]
   WidgetFactoryBatchObject batchMe(&theWidgetFactory);
   // any number of calls to MakeWidget() can go here
   [/code]

   (Making the code exception-safe is left as an exercise to the reader ;^) )

   -Jeremy

2. Jeremy Friesner Says:
   January 2nd, 2009 at 3:11 pm

   Oops, that should be:

   [code]
   void EndMakingWidgetsBatch()
   {
   if (-–widgets_batch_count == 0)
   RestartProcesses();
   }
   [/code]

3. Hostile Fork Says:
   January 8th, 2009 at 4:19 pm

   Hi Jeremy, thanks for visiting the blog (and reading these old entries!)

   You make a good point in matching problem-statement to problem-solution for the specific case I gave. Since I wasn’t taking advantage of any particular property of knowing the number in advance, it was a distracting choice. So I should either use your hint or introduce the allocation number benefit (like, there’s some memory block and knowing the number helps you allocate one block). Since the latter just complicates no reason I’ll go with yours!

   But my main thrust wasn’t any particular prescription for what kind of hints you would make. It was merely the idea of splitting exposed APIs into instructions for which every parameter has semantic meaning… and these “hints” in which ZERO parameters have meaning.

   It encourages clients to write their code in a natural way–and gives the API implementers a chance to be more free in inventing interesting hints based on the specific use cases that clients are encountering. Especially since the program should still work if the implementation were changed to a no-op! Not only will the hinting not break backwards binary compatibility when clients run against old API implementations (assuming the hints aren’t statically linked), but a hint that turns out to be useless can be dropped.

   I’ve always wished it were possible to give these kinds of hints to hardware. Recently I was looking at LLVM and saw they had an instruction for “prefetch” where you can give hints about the locality of your data access:

   http://llvm.org/docs/LangRef.html

   That looks like a pretty cool project overall, perhaps worth delving into…

Leave a Reply