bdlf.h

Go to the documentation of this file.

/// @file bdlf.h
///
///
/// @defgroup bdlf Package bdlf
/// @brief  Basic Development Library Functors (bdlf)
/// @addtogroup bdl
/// @{
/// @addtogroup bdlf
/// [bdlf]: group__bdlf.html
/// @{
///
/// # Purpose {#bdlf-purpose}
/// Provide signature-specific function objects (functors).
///
/// # Mnemonic {#bdlf-mnemonic}
/// Basic Development Library Functors (bdlf)
///
/// @see 
///
/// # Description {#bdlf-description}
/// The 'bdlf' package provides components to implement function
/// objects (functors) that return void and take between zero and nine arguments
/// of arbitrary type.  Function objects created by 'bdlf' components can be
/// invoked in a manner similar to that of the following free function:
/// @code
///   void functionObject(arglist);
/// @endcode
/// where 'arglist' contains between zero and nine arguments.  Functor classes are
/// differentiated by the number and type of arguments they expect.  The 'bdlf'
/// package contains 10 separate components that differ in the number of arguments
/// their functors expect; within each component, templates are used to support
/// variations in argument type.
///
/// In addition, three components (@ref bdlf_bind , @ref bdlf_memfn  and @ref bdlf_function )
/// provide more general functors that can conform to a specified prototype and
/// return an arbitrary type, and that can be invoked in the same manner as
/// before.  The functors created by these two components currently support from
/// zero up to 14 arguments.  @ref bdlf_bind  provides compile-time polymorphism, and
/// adapts an invocable object so that it conforms to a different interface and
/// can be invoked with fewer arguments and/or with the arguments in a different
/// order.  This transformation is type-safe, in that type violations provoke
/// compilation errors.  @ref bdlf_memfn  provides a wrapper that allows a member
/// function to be invoked like a free function, either by providing the object
/// instance as first parameter, or by wrapping the object instance inside the
/// function object.  @ref bdlf_function  provides run-time polymorphism and is
/// especially suited for callbacks because it adapts any invocable with a
/// compatible prototype to a specified callback interface, at run-time and
/// without the need for recompilation.
///
/// ## Hierarchical Synopsis
///
/// The 'bdlf' package currently has 5 components having 3 levels of physical
/// dependency.  The list below shows the hierarchical ordering of the components.
/// The order of components within each level is not architecturally significant,
/// just alphabetical.
/// @code
///  3. bdlf_bind
///
///  2. bdlf_memfn
///     bdlf_noop
///     bdlf_placeholder
///
///  1. bdlf_noop_cpp03                                                  !PRIVATE!
/// @endcode
///
/// ## Component Synopsis
///
///  @ref bdlf_bind :
///       Provide a signature-specific function object (functor).
/// 
///  @ref bdlf_memfn :
///       Provide member function pointer wrapper classes and utility.
/// 
///  @ref bdlf_noop :
///       Provide a functor class that does nothing.
/// 
///  'bdlf_noop_cpp03':                                                  !PRIVATE!
///       Provide C++03 implementation for bdlf_noop.h
/// 
///  @ref bdlf_placeholder :
///       Provide a parameterized placeholder and specialized placeholders.
///
/// ## Related Packages in Package Group bdl
///
/// Package 'bdlf' is designed to use three other packages in 'bdl'.  'bdlf'
/// provides the primary interface that a client will see, and the other packages
/// play supporting roles.
///
/// The packages are:
///
///  'bdlf':
///       Provides functors to clients in a canonical form.
/// 
///  'bdlfr':
///      This package is *DEPRECATED*.  A common reference-counted base class,
///      used by 'bdlfi'.  These classes provide reference counting and object
///      deletion for derived classes.
/// 
///  'bdlfi':
///      This package is *DEPRECATED*.  Concrete reference-counted function
///      objects, held and managed by a 'bdlf' object; classes in 'bdlfi'
///      implement behavior declared in 'bdlfr'.
/// 
///  'bdlfu':
///      This package is *DEPRECATED*.  Factory method utilities to initialize
///      'bdlf' functors by creating a reference-counted function object (from
///      'bdlfi') and assigning it to a 'bdlf' functor. Subsequent invocations of
///      the 'bdlf' functor will be delegated to the  'bdlfi' object.
///
/// ## Relationship to Packages in bdl
///
/// The 'bdlf', 'bdlfr', 'bdlfi', and 'bdlfu' packages provide identical
/// functionality to the corresponding packages in the 'bce' package group:
/// 'bcef', 'bcefr', 'bcefi', and 'bcefu', respectively.  The difference between
/// the two sets of packages is that the 'bce' packages provide thread safety,
/// whereas the 'bdl' packages do not.  In particular, package 'bcefr' implements
/// reference counting via atomic operators provided in package @ref bces_atomicutil .
///
/// ## Functors and Function Pointers
///
/// Function pointers should be familiar to both C and C++ programmers.  A
/// function pointer is a pointer to a C-style function.  In C++, the function
/// pointer is declared to point to a function with a specific return type and a
/// specific number of arguments of specific types.  For instance,
/// @code
///  void (*fp)(int, const char*);
/// @endcode
/// declares a function pointer 'fp' that points to a function returning 'void',
/// and taking exactly two arguments, an 'int' and a const pointer to 'char'.
///
/// Assume, then, that we have one or more functions declared with the matching
/// signature:
/// @code
///  void f1(int x, const char* s);
///  void f2(int x, const char* s);
/// @endcode
/// After assigning a value to the function pointer, we can call the corresponding
/// function:
/// @code
///  fp = f1;
///       .
///       .
///       .
///  int my_x = 0;
///  int my_s = "Text String";
///  fp(my_x, my_s);          // invokes function f1
/// @endcode
/// Functors are objects that behave syntactically and semantically like
/// functions.  Functors implement a function-call operator ('operator()') whose
/// signature characterizes the particular functor's type.  In this example, for
/// instance, we could define a functor like this:
/// @code
///  class MyFunctor {
///      // Class MyFunctor can be used like a function.
///       .
///       .
///       .
///  public:
///      void operator()(int x, const char* s);
///      // this provides invocation semantics
///       .
///       .
///       .
///  };
///
///  MyFunctor fn;
///       .
///       .
///       .
///  int my_x = 0;
///  int my_s = "Text String";
///  fn(my_x, my_s);          // "invokes" functor fn via fn::operator()
/// @endcode
/// Functors provide some interesting advantages over simple function pointers.
/// Unlike a function pointer, a functor may be created with one or more arbitrary
/// objects (sometimes called "user data") to be passed (typically as trailing
/// arguments) to the underlying function.  By "pre-binding" particular arguments
/// to the underlying function, a functor can reduce the number of arguments a
/// caller must supply when the functor is invoked.  In this way, function objects
/// can be used to coerce functions with extra arguments of arbitrary type into a
/// standard calling signature.  Even (non-'static') *member* functions can be
/// encapsulated within functors and treated uniformly, simply by supplying the
/// appropriate object at construction.  Both the *object* pointer and a *member*
/// *function* pointer are stored in the functor; the given object pointer is
/// dereferenced when the functor is invoked.
///
/// ## Functors in the bdlf package
///
///
/// ### Signature-Specific Functors
///
/// Individual components are "numbered" to indicate the number of arguments
/// (between 0 and 6) that a particular functor accepts.  Each component defines a
/// templated class, whose template parameters correspond in number to the functor
/// arguments.  When instantiated, the template argument types match the argument
/// types used in invoking the functor.  The component name is @ref bdlf_vfunc 
/// followed by 0 to 6; the letter 'v' indicates that the corresponding functor
/// will return 'void'.  For the example above, we would use component
/// @ref bdlf_vfunc2  to create a functor object whose 'operator()' member function
/// obeys the required signature.
/// @code
///  #include <bdlf_vfunc2.h>
///
///      bdlf_Vfunc2<int, const char*> fn;  // template arguments specify arg
///                                         // types
///          // NOTE: This example is incomplete.
///          //       We still need code to initialize 'fn'
///      .
///      .
///      .
///      int my_x = 0;
///      int my_s = "Text String";
///      fn(my_x, my_s);                    // "invokes" functor fn
/// @endcode
/// Before a 'bdlf' functor is invoked as illustrated, the client is responsible
/// for ensuring that it is valid; that is, it must contain a pointer to a
/// function that will be called when the functor is invoked.  The function to be
/// called is external to the functor, and supplied by the client.  This "external
/// function" may be a free function, a static class method, or a (non-'static')
/// member function for some class.  The client, then, needs a canonical
/// mechanism, regardless of the function type, to create a reference to that
/// function, and to bind the reference to the 'bdlf' functor.
///
/// The most common way to accomplish this is to use a "factory method" defined in
/// the 'bdlfu' package.  The 'bdlfu' package contains 10 components which provide
/// these factory methods.  Parallel to 'bdlf', these components are "numbered" to
/// support functors with different numbers of arguments.  The factory methods are
/// also templatized to support varying argument types.
///
/// Each 'bdlfu' component contains 4 different types of factory methods, varying
/// by the type of function pointer required.  For example, @ref bdlfu_vfunc2  defines
/// the following *factory* *method* *families*:
/// @code
///  bdlfu_Vfunc2::makeF();    // generate a pointer to a free function
///                            // and assign it to a 'bdlf_Vfunc2' object
///  bdlfu_Vfunc2::makeM();    // generate a pointer to a member function
///                            // and assign it to a 'bdlf_Vfunc2' object
///  bdlfu_Vfunc2::makeC()     // generate a pointer to a const member
///                            // function and assign it to a  'bdlf_Vfunc2'
///                            // object
///  bdlfu_Vfunc2::makeNull(); // initialize a 'bdlf_Vfunc2' object with
///                            // an empty function
/// @endcode
/// These factory methods (except for 'makeNull') are templatized to support
/// different return and argument types; in addition, each *factory* *method*
/// *family* consists of a set of overloaded functions that support varying
/// numbers of arguments on the underlying functions (member or free).  All
/// classes returned by functions in component @ref bdlfu_vfunc2  are defined in
/// component @ref bdlfi_vfunc2 .  See package documentation for the {'bdlfu'} package
/// for details.
///
/// For the simple example above, we would use component 'bdlfu_Vfunc2' as follows
/// to initialize the 'bdlf_Vfunc2' object:
/// @code
///  #include <bdlf_vfunc2.h>
///  #include <bdlfu_vfunc2.h>
///
///      void f1(int x, const char* s);
///      void f2(int x, const char* s);
///
///      bdlf_Vfunc2<int, const char*> fn;  // template arguments define arg types
///      bdlfu_Vfunc2::makeF(&fn,f1);       // bind functor fn to function f1
///         .
///         .
///         .
///      int my_x = 0;
///      int my_s = "Text String";
///      fn(my_x, my_s);                    // "invokes" functor fn
/// @endcode
/// The 'bdlfu_Vfunc2::makeF' *factory* *method* in the above example expects two
/// arguments.  The first is a pointer to the functor object itself, and the
/// second is a pointer to a free function with a signature matching the functor
/// object, that is, expecting args of 'int' and 'const char*', and returning
/// 'void'.
///
/// The 'makeF()' functions create instances of classes from the 'bdlfi'
/// component; the specific classes are determined by the number and types of
/// arguments on the 'bdlf' functor and the free function.  Similarly, class
/// member functions can be used to initialize a 'bdlf' functor by invoking a
/// 'bdlfu_Vfunc2::makeM()' or 'bdlfu_Vfunc2::makeC()' function.
///
/// The 'bdlfu' and 'bdlfi' packages will also allow clients to match a functor to
/// a free or member function in situations where the function requires more
/// arguments than the functor invocation can support.  See the documentation for
/// package {'bdlfu'} for details describing how to do this; see package
/// documentation for {'bdlfi'} for implementation details.
///
/// Note that because each required argument type 'T' is passed by ('const' 'T&'),
/// a compiler will generate an error if the user declares a callback function
/// taking an argument via a non-'const' reference parameter.  This is intended to
/// support and enforce the rule that all modifiable arguments are passed using
/// pointers and not using references.  For rare situations where clients want to
/// use a callback function supplied by a third party, and that callback function
/// uses non-'const' references, a wrapper function must be declared that converts
/// non-'const' references to 'const' references or pointers as appropriate.
///
/// ### Envelope-Letter Idiom
///
/// The functors in the 'bdlf' package are implemented using the envelope-letter
/// idiom.  The classes in 'bdlf' are *"envelopes"*; classes in 'bdlfr' and
/// 'bdlfi' are *"letters"*. The use of the envelope-letter idiom allows clients
/// to wrap arbitrary functions, whose signatures may differ from the function
/// signatures in 'bdlf', with functors that support standard, well-known
/// signatures.
///
/// Each 'bdlf_Vfunc*' functor *(envelope)* holds a pointer to an
/// object *(letter)* from the corresponding 'bdlfi_vfunc*' component.  The 'bdlf'
/// *envelope* forwards or delegates client requests to its *letter* object: in
/// particular, the 'operator()' member function used by clients to invoke the
/// functor is delegated to the *letter* object for execution.
///
/// The *letter* object is polymorphic: all *letter* classes in a given 'bdlfi'
/// component are derived from a common protocol or abstract base class (defined
/// in 'bdlfr').  The 'bdlf' *envelope* uses the abstract 'bdlfr' protocol to
/// delegate invocation requests.  Different polymorphic *letter* types are used
/// to support different external function types and signatures, and the single
/// *envelope* type is used to provide a consistent function signature to clients.
///
/// Since polymorphism is used to support different bindings to external member or
/// free functions, clients must be able to generate a specific type of *letter*
/// object for a given *envelope*, based upon the type and signature of the
/// specific external function.  This may be done directly through public
/// interfaces of the corresponding 'bdlfi' component, but in most cases it is
/// simpler to use a suite of template functions provided by the corresponding
/// 'bdlfu' package.  Different template functions are provided to match (1) the
/// desired function-call-operator signature and (2) the supplied user data.
/// Because the C++ compiler will deduce template parameters from argument types,
/// clients need not specify them.  See the {'bdlfu'} package for more information
/// on populating 'bdlf' functors with specific *letter* objects.
///
/// See also J.O.  Coplien, "Advanced Programming Styles and Idioms", Sections
/// 5.5-5.6, for a complete discussion of the envelope/letter idiom.
///
/// ### Binders
///
/// The @ref bdlf_bind  component provides a mechanism for creating function objects
/// different from the 'bdlf_vfunc*' components.  @ref bdlf_bind  is used to *adapt*
/// an invocable object so that it conforms to a different interface and can be
/// invoked with fewer arguments and/or with the arguments in a different order.
/// It does this by *binding* some or all of the original invocable's arguments to
/// fixed values that are known at construction time and binding the remaining
/// arguments to placeholders for arguments that are provided at invocation time.
/// A binder can be used as an argument for any template function that requires an
/// invocable with compatible parameters.
///
/// The @ref bdlf_bind  component defines binder objects and factory methods that can
/// bind any arguments into a functor in any order, enabling some of the arguments
/// of the invocable to be specified at the construction time, and leaving (via
/// place-holders, defined in component @ref bdlf_placeholder ) some others to be
/// specified (later) at invocation time.  A binder is created by one of the three
/// *factory* *method* *families* defined in component @ref bdlf_bind :
/// @code
///  bdlf_BindUtil::bind();   // generate a binder with specified invocable and
///                           // bound arguments (invocation arguments are
///                           // indicated by place-holders)
///  bdlf_BindUtil::bindA();  // same as above but also specify the allocator
///                           // used to supply memory for creating the binder
///  bdlf_BindUtil::bindR();  // same as 'bdlf_BindUtil::bind()' but explicitly
///                           // specify the return type (in case it cannot be
///                           // deduced by the compiler but should not be left
///                           // undefined)
/// @endcode
/// Binders where the signature of the invocable can be deduced are called
/// *explicit*.  Not all binders are explicit.  For non-explicit binders, the
/// signature of a 'bdlf_Bind' object is not embedded in the type, and several
/// overloads can be invoked through the same binder.  Unlike 'bdlf_Vfunc*'
/// objects, different binders accepting the same signature may have different
/// types depending on the types of the bound arguments if they are non-explicit.
/// The return type (not necessarily void) is also part of the signature.  Thus,
/// @ref bdlf_bind  provides compile-time polymorphism but not run-time polymorphism.
///
/// A broad discussion of binding, along with limitations of the 'usage examples,
/// can be found in the component documentation of component @ref bdlf_bind .
///
/// ### General (Run-Time Polymorphic) Function Objects
///
/// In addition to signature-specific objects and binders, the 'bdlf' package
/// provides a run-time polymorphic 'bdlf_Function' template.  A 'bdlf_Function'
/// instantiation is capable of holding *any* invocable object of compatible
/// prototype, including a function pointer, 'bdlf_MemFn' wrapper, any concrete
/// implementation of the 'bdlfr_Vfunc*'protocols, any instances of the
/// 'bdlf_Vfunc' family, and any other function object having an 'operator()'
/// method including an instance of a 'bdlf_Bind' instantiation.
///
/// Like a binder, a 'bdlf_Function' instantiation can have a return value (or
/// return 'void').  An instance does not store bound arguments directly.  It
/// accepts all its arguments at invocation time only, although using polymorphic
/// representations and the 'bdlfu_Vfunc*::make*' factory methods, it is possible
/// to bind the last arguments of an invocable and wrap this into a
/// 'bdlf_Function' object which will then accept only the remaining arguments
/// upon invocation.  As mentioned above, it is also possible to assign a
/// 'bdlf_Bind' object to a 'bdlf_Function' instance to bind and route arguments
/// to the invocable in an arbitrary manner.
///
/// Unlike a binder, the signature of a 'bdlf_Function' object is part of the type
/// and invocation arguments are cast to their corresponding type before they are
/// passed to the invocable.  Most importantly, the same functor may be assigned
/// from various types (pointer to function, 'bdlf_MemFn' wrapper, user-defined
/// function objects, or even 'bdlf_Bind' binders).
///
/// ### Functors and Binders
///
/// 'bdlf_Function' objects (functors) and 'bdlf_Bind' objects (binders) are both
/// mechanisms for binding arguments and calling an invocable.  They differ in
/// their purpose, though.  In the last section, we detailed the main features of
/// the @ref bdlf_function  and @ref bdlf_bind  components.  In this section we point out
/// the differences, and how they interact.
///
/// The main difference is compile-time (for @ref bdlf_bind ) vs. run-time (for
/// @ref bdlf_function ) polymorphism.  An instantiation of 'bdlf_Function' is a type
/// of functor that can hold any invocable object with compatible prototype.
/// Regardless of what type of (compatible) invocable is used to create the
/// 'bdlf_Function', the type of the resulting functor does not change.  Thus,
/// 'bdlf_Function' has run-time polymorphism and is ideally suited for callbacks
/// because it *adapts* the invocable to the callback interface.  Run-time
/// polymorphism is extremely useful for defining callback types and storing
/// callbacks, since passing a new type of callback does not require
/// re-compilation.  Compile-time polymorphism provides the ability to invoke
/// several overloads through the same functor (binder) and to bind and route
/// arguments to the invocable in an arbitrary manner.
///
/// In cases where both binders and functors could be used, 'bdlf_Function' has
/// certain advantages, not least of which is simplicity (leading to shorter
/// compilation times), and the memory optimization documented below, whereby
/// small objects are constructed in-place but larger objects are dynamically
/// allocated.  Note that binders are always constructed in-place and can have
/// rather large footprints.  Functors (including instances of 'bdlfr_Vfunc*'
/// derived types) can implement various strategies like sharing and copy-on-write
/// to reduce the cost of copying and the footprint at the same time.
///
/// ## Usage
///
/// 'bdlf'-style functors provide a type-neutral, exception-safe (and
/// *potentially*, but not yet, thread-safe) *properly* *managed* alternative to
/// the traditional callback paradigm (where "client data" is placed in a single
/// structure whose address is cast to type 'void *').  The following example
/// illustrates how functor callbacks can be added to a graphical object.
///
/// Let's suppose that the implementor of the 'MyGuiButton' class allows the
/// client to specify a callback function that should be called whenever a button
/// is pressed.  Furthermore, the implementor agrees to provide to the callback
/// function two arguments at its invocation: a modifiable object of type
/// 'MyGuiContext', and a non-modifiable object of type 'MyGuiLocation'.
/// @code
///  class MyGuiContext {
///      int d_changedFlag;
///
///    public:
///      MyGuiContext() : d_changedFlag(0) { }
///      int isChanged() { return d_changedFlag; }
///      void changeState() { ++d_changedFlag; }
///
///      // 'MyGuiContext' implementation
///  };
///
///  class MyGuiLocation {
///    public:
///      MyGuiLocation() { };
///
///      // 'MyGuiLocation' implementation
///  };
/// @endcode
/// Here is the implementation of the 'MyGuiButton' class:
/// @code
///  class MyGuiButton  {
///      bdlf_Vfunc2<MyGuiContext *, MyGuiLocation> d_callback;
///          // Functor to execute when button is pressed.
///
///    public:
///      MyGuiButton(const bdlf_Vfunc2<MyGuiContext *,
///                  MyGuiLocation>& buttonPressCallback);
///          // Create a graphical button object that executes the
///          // specified callback when 'pressButton' is invoked.
///
///      void pressButton(MyGuiContext *context,
///                       const MyGuiLocation& location);
///          // Execute the callback owned by this button object.
///  };
///
///  MyGuiButton::MyGuiButton(const bdlf_Vfunc2<MyGuiContext *,
///                           MyGuiLocation>& buttonPressCallback)
///  : d_callback(buttonPressCallback) // Retain a "copy" of the specified
///                                    // functor.
///  {
///  }
///
///  void MyGuiButton::pressButton(MyGuiContext *context,
///                                const MyGuiLocation& location)
///  {
///      d_callback(context, location);
///          // Execute the contained callback object.
///  }
/// @endcode
/// The 'context' and 'location' arguments are mandatory for every function called
/// at the press of the button (the number '2' in the name of 'bdlf_Vfunc2' class
/// specifies the number of required arguments).  However, we also allow the user
/// of 'MyGuiButton' class to invoke the function with a number of additional
/// parameters, as in the 'buttonpressFunction' function presented below.
/// @code
///  static void buttonpressFunction(MyGuiContext *a,
///                                  const MyGuiLocation& b,
///                                  int *invocationCounter)
///      // This function will be invoked by a functor to increment the
///      // specified 'invocationCounter'.
///  {
///          a->changeState();
///          ++*invocationCounter;
///  }
/// @endcode
/// The 'bdlf_Vfunc2<MyGuiContext, MyGuiLocation>' class used in 'MyGuiButton'
/// class has a private member of an abstract class @ref bdlfr_vfunc2 , whose
/// 'execute' method is called when the functor is being called.  The 'execute'
/// method of the @ref bdlfr_vfunc2  class, the functor invocation operator of the
/// 'bdlf_Vfunc2' class, and the 'pressButton' method of 'MyGuiButton' class have
/// two parameters.  The 'buttonpressFunction' callback function, however, has to
/// be called with three arguments.  To achieve the proper calling signature the
/// user implements a concrete class derived from @ref bdlfr_vfunc2  as follows:
/// @code
///  template <class F, class A1, class A2, class D1>
///  class FuncRep : public bdlfr_Vfunc2<A1, A2> {
///      // This class defines the representation for a function object (functor),
///      // characterized by a function-call operator taking two arguments and
///      // returning 'void', that holds a pure procedure (i.e., free function,
///      // static member function, or functor) taking one additional trailing
///      // argument, and this argument's corresponding value.
///
///      F  d_f;  // function pointer or function object (functor)
///      D1 d_d1; // first embedded argument
///
///    private:
///      // not implemented
///      FuncRep(const FuncRep<F, A1, A2, D1>&);
///      FuncRep<F, A1, A2, D1>& operator=(const FuncRep<F, A1, A2, D1>&);
///
///    private:
///      ~FuncRep()
///          // Destroy this functor.  Note that destructor can be invoked only
///          // through the static 'deleteObject' method of the base class.
///      {
///      };
///
///    public:
///      // CREATORS
///      FuncRep(const F&         procedure,
///              const D1&        embeddedArg1,
///              bdlma_Allocator *basicAllocator)
///          // Create a representation for a function object (functor) taking two
///          // arguments and returning 'void', using the specified 'procedure'
///          // taking 1 additional trailing argument, and this argument's
///          // specified 'embeddedArg1' value.  Use the specified
///          // 'basicAllocator' to supply memory.
///      : bdlfr_Vfunc1<A1, A2>(basicAllocator)
///      , d_f(procedure)
///      , d_d1(embeddedArg1)
///      {
///      };
///
///      // ACCESSORS
///      void execute(const A1& argument1, const A2& argument2) const
///          // Invoke the underlying procedure (free function, static member
///          // function, or functor) with the specified 'argument1' and
///          // 'argument2' followed by the argument value specified at
///          // construction.
///      {
///          d_f(argument1, argument2, d_d1);
///      };
///  };
/// @endcode
/// Note that the required arguments are passed in at the functor invocation, and
/// optional arguments are passed in at the functor initialization.  By BDE
/// convention, a function signature consists of output parameters, and then input
/// parameters.  Since here we have two parameter lists (one passed in by the
/// caller, and one passed in by the callee) we can follow this convention within
/// each list only.  We choose to pass in first the required arguments (passed by
/// the caller) and then the optional arguments (supplied by the callee).  This
/// order allows a callee to add parameters easily at the end of the function
/// parameter list.  The number of required parameters is a part of the
/// 'MyGuiButton' interface, and hence will never change.
///
/// The following code shows how we:
///
///  1. Create the functor representation-(letter).
/// 
///  2. Create the functor initialized with the representation.
/// 
///  3. Register the functor as a callback with an instance of the 'MyGuiButton'
///    class.
/// 
///  4. Invoke the functor.
///
/// The code is as follows:
/// @code
///  // (1) Create the representation.
///
///  typedef void (*BpFun)(const MyGuiContext *, const MyGuiLocation&, int *);
///  bdlma_Allocator *myAllocator = bdlma_Default::defaultAllocator();
///
///  int globalCounter = 0;
///
///  bdlfr_Vfunc2<MyGuiContext *, MyGuiLocation>  *rep = new(myAllocator)
///      FuncRep<BpFun, MyGuiContext *, MyGuiLocation, int*>
///          (buttonpressFunction, &globalCounter, myAllocator);
///
///  // (2) Create the functor using the representation.
///
///  bdlf_Vfunc2<MyGuiContext *, MyGuiLocation> callbackFunctor(rep);
///
///  // (3) Register the functor as a callback.
///
///  MyGuiButton button(callbackFunctor);
///
///  // (4) Use the object.
///
///  MyGuiContext gc;
///  const MyGuiLocation gl;             assert(0 == globalCounter);
///                                      assert(0 == gc.isChanged());
///  button.pressButton(&gc, gl);        assert(1 == globalCounter);
///                                      assert(1 == gc.isChanged());
///  button.pressButton(&gc, gl);        assert(2 == globalCounter);
///                                      assert(2 == gc.isChanged());
/// @endcode
///
/// @}
/** @} */