toast miscellaneous utilities

Detailed Description

This group contains all the little one class or couple of function utilities that didn't really justify their own module. They include toast::compare, toast::global, toast::illegal_cast, toast::scope_guard, toast::type_info, toast::typed_factory, and TOAST_STATIC_INIT_PROTECTED.


file  algorithm.hpp
 This file contains the toast::compare template.
file  concept_check.hpp
 This file contains the TOAST_CLASS_REQUIRE macros.
file  global.hpp
 This file contains the toast::global template.
file  illegal_cast.hpp
 This file contains the toast::illegal_cast template.
file  scope_guard.hpp
 This file contains the toast::scope_guard class.
file  static_init_protected.hpp
 static_init_protected.hpp contains the TOAST_STATIC_INIT_PROTECTED macro.
file  typed_factory.hpp
 typed_factory.hpp contains the toast::typed_factory template class
file  typeinfo.hpp
 This file contains the toast::type_info class.


class  toast::scope_guard
 calls a function on destruction unless dismissed More...
class  typed_factory< T >
 An object that holds arguments for deferred object creation. More...
class  toast::type_info
 provides a 'portable' layer to std::type_info. More...


#define TOAST_CLASS_REQUIRE2(a, b, c, d)   BOOST_CLASS_REQUIRE2(a,b,c,d)
#define TOAST_CLASS_REQUIRE3(a, b, c, d, e)   BOOST_CLASS_REQUIRE3(a,b,c,d,e)
#define TOAST_CLASS_REQUIRE4(a, b, c, d, e, f)   BOOST_CLASS_REQUIRE4(a,b,c,d,e,f)
 A workaround for the static initialization order problem.


template<typename T>
int toast::compare (T const &a, T const &b)
 compare two objects
template<typename T, typename Compare>
int toast::compare (T const &a, T const &b, Compare comp)
 compare two objects according to some predicate
template<typename T>
int(*)(T const &, T const &) toast::get_compare ()
 overload disambiguation helper
template<typename T>
T & toast::global ()
 Naive singleton.
template<typename T, typename V>
toast::illegal_cast (V v)
 perform casts not supported by the standard operators.
template<typename T>
type_info const & toast::type_id ()
 get a toast::typeinfo for type T.
template<typename T>
type_info const & toast::type_id (T const &t)
 get a toast::typeinfo for object t (not necessarily T).

Define Documentation



On Sun's compiler BOOST_CLASS_REQUIRE from the Boost concepts library does not compile. These macros are simple wrappers that will use the Boost concepts library if possible and otherwise will do nothing.

name   ) 


struct private_dummy_toast_detail_nested_type_##name##__ {}; \
        typedef toast::detail::static_init_protected<T, private_dummy_toast_detail_nested_type_##name##__> name
A workaround for the static initialization order problem.

In C++ the initialization order of static variables within a single module is defined, but not between modules. This class solves this issue by lazily creating the T parameter on first use, but still guarantees that the object has been initialized by the first line of main(). This behavior is often desirable when writing multithreaded code -- you want something to be lazily initialized to work around static initialization order, but you don't want it to be so lazy that it isn't initialized until first use because then you have to worry about locking (once main begins things can become multithreaded, while static initialization is always single threaded -- at least it *should be* single threaded -- on most platforms creating threads during static initialization causes a crash because data threading relies on is setup during static initialization. If your compiler lets you get away with this it is still bad form to do so -- otherwise simply dynamically linking a module at runtime could cause threads to spawn! Always require users to explicitly opt-in to cost heavy operations).

By invoking the macro, you will create a special unique type with a static get() method for extracting your static-initialization-protected object. Example:


 struct Foo {
     int x;
     Foo() { x = 5; }

 F& theFoo();



 F& theFoo() { return protected_Foo::get(); }

The macro creates a typedef called protected_Foo. The type being typedef'd has a static get() method for retrieving the T inside, in this case a Foo.

Then in another module B:


 #include "moduleA.hpp"

 static int myval = theFoo().x;

 int main()
     std::cout << myval << std::endl;

This will print 5 even if module B is initialized before module A. Also, protected_Foo's x member will be set to 5 before the first line of main even if we remove module B.

Don't create variables of the typedef'd type. Instead use the static get() method on the type. If you try to instantiate an object of the typedef'd type you'll get a compile error.

This only works to make static 'variables' (really typedefs with a get() method) at the namespace or class level. You can't use TOAST_STATIC_INIT_PROTECTED to create a static function variable.

Function Documentation

template<typename T, typename Compare>
int toast::compare ( T const &  a,
T const &  b,
Compare  comp 
) [inline]

compare two objects according to some predicate

the predicate should take two objects and return true or false. Given the predicate of std::less, compare will return 1 if the first argument is greater, 0 if it is equal, and -1 if it is less than the second argument. Obviously its behaviour will be different depending on the predicate, but this should give enough information for you to figure it out.

Referenced by toast::get_compare().

template<typename T>
int toast::compare ( T const &  a,
T const &  b 
) [inline]

compare two objects

requires the objects support operator<. Will return 1 if the first argument is greater, 0 if it is equal, and -1 if it is less than the second argument.

template<typename T>
int(*)(T const &, T const &) toast::get_compare (  )  [inline]

overload disambiguation helper

because getting the address of overloaded functions sucks in C++, I've provided 'easy accessors' here to be able to pass around the address of the compare you want without casting. This is useful if you need to pass the function pointer to boost::bind, or perhaps to Boost.Python's def.

Use get_compare<T> to get the version without a predicate, and get_compare<T, Compare> to get the version with a predicate.

References toast::compare().

template<typename T>
T& toast::global (  )  [inline]

Naive singleton.

Templatized implementation of Scott Meyers simple singleton [1]. It doesn't actually turn T into a singleton, but it does ensure that everyone accessing T through this function is accessing the same T. It doesn't address the Dead Reference Problem, but is still very useful.

There may only be one global per T using this function. Generally only one module (often the application) should be the 'owner' of this global (i.e. the initializer and modifier of the global for other modules use).

Keep in mind that typedefs are NOT unique types. For structs or classes a unique type can be created as needed through public inheritance.

The global<T> will be initialized on the first call to global<T>(), unless T is a POD type, in which case the initialization happens at startup (standard semantics for a static function variable). T must be default constructible.

[1] p.222 Effective C++ (second edition)

template<typename T, typename V>
T toast::illegal_cast ( v  )  [inline]

perform casts not supported by the standard operators.

It turns out that there are a couple of casts that aren't even possible with std::reinterpret_cast!! Rather than resorting to C-Style casts for these we've chosen to create this template for easy grep'ing and plenty of ugliness.

Only two casts may currently be performed this way. From a function pointer to a void pointer, and from a bool to a void pointer. Logo