You can think of a functor as an object that contains a function and the information necessary to invoke that function. Functors are also called function objects, or sometimes method or command objects. A functor acts as a sort of adapter that lets a program launch a function from any source without knowing the specifics of the function's signature. Functors were always an important part of Threads.h++, but in this release they have been uncovered for you and extended with the addition of functor maps and functor lists. The Functor package provides a convenient, flexible, and powerful way to encapsulate function calls.1
A functor captures the information necessary to describe and make a call to a specific function, including the function itself and any argument values to pass to it. The functor's interface can be quite independent of the encapsulated function. Because the information for invoking the function is encapsulated in an object, the invocation can be deferred or delegated. Software components can pass a functor as a parameter or return value, like any other object. Functors make it straightforward to write a tool that can accept and carry out any arbitrary piece of work. Instead of trying to deal with a variety of unknown function signatures, such a tool takes one type of functor, whose arguments and return value fit the tool's own requirements. Each functor handles the details of adapting its encapsulated function to those requirements.
The Functor package provides the following features:
Functors are type flexible. Their parameters are templates, which ensures consistent interfaces and code generation by the compiler.
Functors are object-oriented and generic. You can use them in any situation, like any other object.
Functors implement a consistent interface for different functions. The encapsulated function need not match the functor's signature exactly, as long as the types are convertible.
Functors are convenient. Once you abstract out the notion of a function to a functor object, you can reuse the functor in any number of situations.
Functors are an easy way to exchange information about functions, because you are dealing with an object, rather than a function pointer.
Functors are compile-time type safe. The compiler does the type conversions. If you try to make a functor out of a function that is not compatible with the functor type, you get a compiler error.
In addition to basic functors, the Functor package includes two subpackages:
Functor lists, described in Section 8.6, "The Functor List Subpackage." If you need to call more than one functor per invocation, use functor lists.
Functor maps, described in Section 8.7, "The Functor Map Subpackage." If you're calling one functor per invocation, but you have multiple functors to choose from, use a functor map.
The subpackage software resides in separate directories under each of the functor directories.
The Functor package depends on the Thread-compatible Exception, Execution Tracing, Synchronization, and Smart Pointer packages of Threads.h++. You can build the two Functor subpackages, Functor Lists and Functor Maps, independently of each other, but they each require the basic Functor package.
Because there are so many header files, the Functor package provides six umbrella header files in the rw\functor directory: functor0.h, functor1.h, functor2.h, functorR0.h, functorR1.h, and functorR2.h. Each of these files includes the header files for a subset of the functor classes. If you are using a single handle class, include the header file whose name matches the handle class. If you are using multiple handle classes, you can access the declarations for the entire Functor package by including the functor.h file.
Each subpackage has an umbrella file to that includes all its header files. For functor lists, it is rw\functor\list\list.h, and for functor maps, it is rw\functor\map\map.h. If you are using only a few of the classes, however, you can include each file individually to avoid pulling in unnecessary classes.
Functors are convenient for solving some common problems. The functor classes offer a consistent way to implement a callback interface. Suppose you have two separate software components, and component A calls component B. The functor encapsulates a function supplied by component B, and adapts that function to the signature expected by the calling function in component A. Functors solve the problem of calling unknown objects in C++. When you develop a component, all you need to know is what data it needs to send to the unknown object and what it needs to receive in return, and specify the appropriate functor type. In this way, functors can connect libraries from different sources.
Functors are required, in some cases, when you use other Threads.h++ packages. In multithreaded applications, for example, you can pass a functor to tell a new thread where to begin execution. You also use functors to create runnable classes whose instances can execute any function. See Section 3.4, "Using Threads."
Functors also provide a level of abstraction useful for functional programming and creating higher-order functions.
In Threads.h++, functors are implemented by a large number of template classes for global, static, and member function calls. A variety of functors accommodates different numbers of arguments and different ways of handling the return type. The functor classes overload operator() to supply a function call operator that invokes the encapsulated function. When the caller calls the functor, the syntax is identical to a function invocation.
What we have, then, is a caller, some software routine that invokes the functor, and a callee, the software that provides the function that is encapsulated by the functor. Any place you would want to pass a function pointer to the caller, you can pass a functor. If necessary, the functor can adapt the callee function to the signature that the caller expects. The functor cannot make every function fit, but it can deal with extra arguments, a return value when none is wanted, and a less than exact match in argument and return types.
For example, suppose the calling routine needs to call various functions with one argument value of type char and to receive a double in return. The routine can be written to call a functor type that takes one argument and returns a value, in this case RWTFunctorR1<double,char>. This is all the caller has to do. Everything else is the callee's responsibility.
The callee selects one of its functions, which it uses to build a functor of type RWTFunctorR1<double,char>. The simplest case is a function that matches the functor invocation, like this:
double function1 (char c);
In this case, the functor contains only a function pointer. The functor just passes the argument from the caller to the function and passes the return value from the function to the caller. The process looks something like Figure 45.
The caller calls the functor with its char argument:
functor1('y');
When the caller passes argument values directly to the functor like this, the arguments are called caller data. The functor, in turn, passes the value on when it launches the function:
function1('y');
The function sends its return value back to the functor, which in turn passes it to the caller.
Suppose that another function has an argument that will always take the same value when invoked by the functor. The function looks like this:
double function2 (char c,double f);
Instead of requiring the value of the double to be specified at every invocation, the functor stores the value and adds it to the end of the function call. When the functor object is constructed, for example, a value of 3.14 might be specified for the second argument. That value always stays the same for every function call. Arguments like this, which are stored within the functor for as long as it exists, are often referred to as callee or client data. In this case, the functor contains both a function pointer and callee data.
The caller knows nothing about the second argument. The caller invokes the functor with one argument:
functor2('y');
but the functor adds the second argument when it launches the function:
function2('y',3.14);
Now the process looks something like Figure 46.
NOTE: The arguments stored as callee data must be the last ones in the function's signature, because the functor adds its callee arguments to the end of the function call.
You can use callee data to handle a function that has more arguments than the functor invocation specifies, provided that the extra arguments do not have to change across calls.
The previous examples have used the function's return value, but suppose we have a different caller that needs to call functions with one char argument, but does not use a return value. This routine is written to call a functor of type RWTFunctor1<char>. The name ending in 1, instead of R1, means the functor does not return a value.
NOTE: A routine that is not going to use the return value should never specify a functor that has one, to avoid limiting the functions the routine can access.
A functor without a return value, like RWTFunctor1, can encapsulate a function with any return type. A functor that specifies a return value, like RWTFunctorR1, can encapsulate only functions with convertible return types.
Now suppose the callee wants to supply this function to the caller:
double function3 (char c);
A functor without a return value automatically ignores the function's return value. The caller never sees it. In this case, the process looks something like Figure 47.
Nothing different is required in the invocation. The caller calls the functor in the usual way:
functor3('y');
and the functor calls the function:
function3('y');
Now let's go back to the caller that needs a return value and takes a functor of type RWTFunctorR1<double,char>. Suppose the callee needs to supply this function:
int function4 (int i);
The difference between the types of the functor invocation arguments and those of the function may look like a problem, but it really isn't. Functors have some type flexibility, and the compiler does the conversions.
The types of the function's arguments and return value must be compatible with the functor's, but they do not have to match exactly. Compatibility requires the types to be convertible. Often the conversion is type promotion, which means the more specific type is promoted to a more general type as the value moves through the process. Keep in mind that argument values and return values are passed in opposite directions.
Arguments - The functor's argument types must be convertible to the function's argument types, because the functor passes its arguments to the function.
Return value - The function's return type must be convertible to the functor's return type, because the function passes its return value back to the functor.
At compile time, the functor's char argument is promoted to the int that the function expects. The function's int return value is promoted to the functor's double. The caller calls the functor in the usual way:
functor4('y');
and the functor calls the function:
function4(int('y'));
The process looks something like Figure 48.
©Copyright 2000, Rogue Wave Software, Inc.
Contact Rogue Wave about documentation or support issues.