(For the complete, working source of this example see allocators.cpp)

Boost.Mixin allows you to set custom allocators for the persistent pieces of memory the library may require.

The library allocates some memory on initialization, which happens at a global scope – before the entry point of a program. It also has some allocations which are for instances with a very short lifetime. Currently those are not covered by the allocators.

What you can control with the custom allocators is the new memory allocated for boost::mixin::object instances - their internal mixin data. You can assign a global allocator to the library and you can also set individual allocators per mixin type.

First let's see how you can create a global allocator. Let's assume you have a couple of functions of your own that allocate and deallocate memory in some way specific to your needs:

char* allocate(size_t size);
void deallocate(char* buffer);

To create a global allocator, you need to create a class derived from global_allocator and override its virtual methods.

class custom_allocator : public boost::mixin::global_allocator
{

The first two methods allocate a buffer for the mixin data pointers. Every object has pointers to its mixins within it. This is the array of such pointers. The class global_allocator has a static constant member – mixin_data_size – which you should use to see the size of a single element in that array.

virtual char* alloc_mixin_data(size_t count)
{
    return allocate(count * mixin_data_size);
}

virtual void dealloc_mixin_data(char* ptr)
{
    deallocate(ptr);
}

The other two methods you need to overload allocate and deallocate the memory for an actual mixin class instance. As you may have already read, the buffer allocated for a mixin instance is bigger than needed because the library stores a pointer to the owning object immediately before the memory used by the mixin instance.

That's why this function is not as simple as the one for the mixin data array. It has to conform to the mixin (and also object pointer) alignment.

virtual void alloc_mixin(size_t mixin_size, size_t mixin_alignment, char*& out_buffer, size_t& out_mixin_offset)
{

The users are strongly advised to use the static method global_allocator::calculate_mem_size_for_mixin. It will appropriately calculate how much memory is needed for the mixin instance such that there is enough room at the beginning for the pointer to the owning object and the memory alignment is respected.

size_t size = calculate_mem_size_for_mixin(mixin_size, mixin_alignment);
out_buffer = allocate(size);

After you allocate the buffer you should take care of the other output parameter - the mixin offset. It calculates the offset of the actual mixin instance memory within the buffer, such that there is room for the owning object pointer in before it and all alignments are respected.

You are encouraged to use the static method global_allocator::calculate_mixin_offset for this purpose.

    out_mixin_offset = calculate_mixin_offset(out_buffer, mixin_alignment);
}

The mixin instance deallocation method can be trivial

virtual void dealloc_mixin(char* ptr)
{
    deallocate(ptr);
}

To use the custom global allocator you need to instantiate it and then set it with set_global_allocator. Unlike the mutation rules, the responsibility for the allocator instance is yours. You need to make sure that the lifetime of the instance is at least as long as the lifetime of all objects in the system.

Unfortunately this means that if you have global or static objects, you need to create a new pointer that is, in a way, a memory leak. If you do not have global or static objects, it should be safe for it to just be a local variable in your program's entry point function.

custom_allocator alloc;
boost::mixin::set_global_allocator(&alloc);

As we mentioned before, you can have an allocator specific for a mixin type.

A common case for such use is to have a per-frame allocator – one that has a preallocated buffer which is used much like a stack, with its pointer reset at the end of each simulation frame (or at the beginning each new one). Let's create such an allocator.

First, a mixin instance allocator is not necessarily bound to a concrete mixin type. You can have the same instance of such an allocator set for many mixins (which would be a common use of a per-frame allocator), but for our example let's create one that is bound to an instance. We will make it a template class because the code for each mixin type will be the same.

A mixin instance allocator needs to be derived from the class mixin_allocator. You then need to overload its two virtual methods which are exactly the same as the mixin instance allocation/deallocation methods in global_allocator.

template <typename Mixin>
class per_frame_allocator : public boost::mixin::mixin_allocator
{
private:
    static const size_t NUM_IN_PAGE = 1000;

    size_t _num_allocations; // number of "living" instances allocated
    const size_t mixin_buf_size; // the size of a single mixin instance buffer
    vector<char*> _pages; // use pages of data where each page can store NUM_IN_PAGE instances
    size_t _page_byte_index; // index within a memory "page"
    const size_t page_size; // size in bytes of a page

public:

    // some way to obtain the instance
    static per_frame_allocator& instance()
    {
        static per_frame_allocator i;
        return i;
    }


    per_frame_allocator()
        : _num_allocations(0)
        , mixin_buf_size(
            calculate_mem_size_for_mixin(
                sizeof(Mixin),
                boost::alignment_of<Mixin>::value))
        , page_size(mixin_buf_size * NUM_IN_PAGE)
    {
        new_memory_page();
    }

    void new_memory_page()
    {
        char* page = new char[page_size];
        _pages.push_back(page);
        _page_byte_index = 0;
    }
    virtual void alloc_mixin(size_t mixin_class_size, size_t mixin_alignment, char*& out_buffer, size_t& out_mixin_offset)
    {
        if(_page_byte_index == NUM_IN_PAGE)
        {
            // if we don't have space in our current page, create a new one
            new_memory_page();
        }

        out_buffer = _pages.back() + _page_byte_index * mixin_buf_size;

        // again calculate the offset using this static member function
        out_mixin_offset = calculate_mixin_offset(out_buffer, mixin_alignment);

        ++_page_byte_index;
        ++_num_allocations;
    }

    virtual void dealloc_mixin(char* buf)
    {
#if !defined(NDEBUG)
        // in debug mode check if the mixin is within any of our pages
        for(size_t i=0; i<_pages.size(); ++i)
        {
            const char* page_begin = _pages[i];
            const char* page_end = page_begin + page_size;

            BOOST_ASSERT(buf >= page_begin && buf < page_end);
        }
#else
        buf; // to skip warning for unused parameter
#endif
        // no actual deallocation to be done
        // just decrement our living instances counter

        --_num_allocations;
    }

    // function to be called once each frame that resets the allocator
    void reset()
    {
        BOOST_ASSERT(_num_allocations == 0); // premature reset
        for(size_t i=1; i<_pages.size(); ++i)
        {
            delete[] _pages[i];
        }

        _page_byte_index = 0;
    }
};

Now this class can be set as a mixin allocator for a given mixin type. A side effect of the fact that it's bound to the type is that it keeps mixin instances in a continuous buffer. With some changes (to take care of potential holes in the buffer) such an allocator can be used by a subsystem that works through mixins relying on them being in a continuous buffer to avoid cache misses.

To illustrate a usage for our mixin allocator, let's imagine we have a game. If a character in our game dies, it will be destroyed at the end of the current frame and should stop responding to any messages. We can create a mixin called dead_character which implements all those the messages with a higher priority than the rest of the mixins. Since every object that has a dead_character mixin will be destroyed by the end of the frame, it will be safe to use the per-frame allocator for it.

First let's create the mixin class and sample messages:

class dead_character
{
public:
    void die() {}
    // ...
};

BOOST_MIXIN_MESSAGE_0(void, die);
BOOST_MIXIN_DEFINE_MESSAGE(die);
//...

Now we define the mixin so that it uses the allocator, we just need to add it with "&" to the mixin feature list, just like we add messages. There are two ways to do so. The first one would be to do it like this:

BOOST_DEFINE_MIXIN(dead_character, ... & boost::mixin::priority(1, die_msg)
    & boost::mixin::allocator<per_frame_allocator<dead_character>>());

This will create the instance of the allocator internally and we won't be able to get it. Since in our case we do care about the instance because we want to call its reset method, we could use an alternative way, by just adding an actual instance of the allocator to the feature list:

BOOST_DEFINE_MIXIN(dead_character, /*...*/ boost::mixin::priority(1, die_msg)
    & per_frame_allocator<dead_character>::instance());

If we share a mixin instance allocator between multiple mixins, the second way is also the way to go.

Now all mixin allocations and deallocations will pass through our mixin allocator:

boost::mixin::object o;

boost::mixin::mutate(o)
    .add<dead_character>();

boost::mixin::mutate(o)
    .remove<dead_character>();

// safe because we've destroyed all instances of `dead_character`
per_frame_allocator<dead_character>::instance().reset();

Currently the maximum number of arguments you can have in a message is:

4

There simply is no message declaration macro for messages with more. If you need macros for messages with more arguments, you can do so, without having to rebuild the library.

In your Boost.Mixin installation, in the gen directory you will see a file, named arity. It is a text file with a single number in it. Edit the file, setting the number to whichever value you need. Then run the script gen_message_macros.rb (you will need a Ruby interpreter to do so). It will generate the file include/boost/mixin/gen/message_macros.ipp with macros for messages with 0 to arity arguments.

If you use an include directory for Boost.Mixin diferent from the one in your installation, you will have to manually copy the newly generated message macros file over the one you use.

As long as the library itself is dynamic (.dll on Windows or .so on Unix or Linux) its safe to use in an application that has dynamic libraries which use Boost.Mixin.

An interesting thing which you can accomplish with the library is to have optional plugins – dynamic libraries that aren't linked with the executable but may or may not be present, and if they are, they are being loaded dynamically (with LoadLibrary or dlopen).

Such plugin may add a mutation rule for its special mixins, or export functions that mutate objects.

For example this may be very useful for an engineering CAD system that could potentially have many different optional plugins for its different needs. Say, a plugin that extends the buildings with electrical wiring could simply mutate objects, adding a mixin mixin called electrical_wiring that contains the appropriate functionality.

There is only one thing you need to remember when you're exporting mixins or messages from a dynamic library: to use the export macros: BOOST_DECLARE_EXPORTED_MIXIN and BOOST_MIXIN_EXPORTED_xxx_MESSAGE_N. They are exactly like their regular counterparts but for their first argument, which is the compiler specific export symbol (__declspec(dllexport) for Visual C++ or just BOOST_SYMBOL_EXPORT if you're using Boost).

One of the examples that come with the library illustrates how you can have the two types of dynamic libraries – one which you link with, and one plugin.

(For the complete, working source of this example see serialization.cpp)

Of course dealing with objects in a complex system means also having some way to save and load them. Be it from a file, database, or through a network. We did mention serialization before in our examples but we never gave an example of how you can serialize boost::mixin::object-s.

The main issue would be how to convert the object's type information to a string and then use this string to create an object with the same type information. As for the concrete serialization of the data within the mixins, this example will only offer a very naïve approach. We don't recommend that you use such an approach for your mixins as it is not safe, and not backward compatible. We only use it here because it's very easy to write and the focus of this example is on the object type information.

Basically what we'll do here to save and load the data inside the mixins is rely on two multicast messages – save and load – which will have a given priority for each mixin. Thus ensuring the order of execution to be the same in loading as it is in saving. Each save and load method of the mixin type will assume it has the right data to save and load.

So, let's declare and define our messages.

BOOST_MIXIN_CONST_MULTICAST_MESSAGE_1(void, save, ostream&, out);
BOOST_MIXIN_MULTICAST_MESSAGE_1(void, load, istream&, in);

BOOST_MIXIN_DEFINE_MESSAGE(save);
BOOST_MIXIN_DEFINE_MESSAGE(load);

Now let's define some simple mixins. For this example we'll assume we're writing a company management system, which has a database of key individuals – employees and clients.

class person
{
public:
    void set_name(const string& name) { _name = name; }

    void save(ostream& out) const;
    void load(istream& in);

    static const int serialize_priority = 1;

private:
    string _name;
};
BOOST_DEFINE_MIXIN(person,
    boost::mixin::priority(person::serialize_priority, save_msg)
    & boost::mixin::priority(person::serialize_priority, load_msg));

class employee
{
public:
    void set_position(const string& position) { _position = position; }

    void save(ostream& out) const;
    void load(istream& in);

    static const int serialize_priority = 2;

private:
    string _position;
};
BOOST_DEFINE_MIXIN(employee,
    boost::mixin::priority(employee::serialize_priority, save_msg)
    & boost::mixin::priority(employee::serialize_priority, load_msg));

class client
{
public:
    void set_organization(const string& position) { _organization = position; }

    void save(ostream& out) const;
    void load(istream& in);

    static const int serialize_priority = 3;

private:
    string _organization;
};
BOOST_DEFINE_MIXIN(client,
    boost::mixin::priority(client::serialize_priority, save_msg)
    & boost::mixin::priority(client::serialize_priority, load_msg));

Now let's declare the save and load functions for an object.

Because in this example they're stand-alone functions, like the messages, we can't just name them save and load, because they'll clash with the message functions defined by the message macros. So let's just name them save_obj and load_obj.

void save_obj(const boost::mixin::object& o, ostream& out);
void load_obj(boost::mixin::object& o, istream& in);

Assuming those functions are written and work correctly, we could write some code with them like this.

First we create some objects:

boost::mixin::object e;
boost::mixin::mutate(e)
    .add<person>()
    .add<employee>();

e.get<person>()->set_name("Alice Anderson");
e.get<employee>()->set_position("Programmer");

boost::mixin::object c;
boost::mixin::mutate(c)
    .add<person>()
    .add<client>();

c.get<person>()->set_name("Bob Behe");
c.get<client>()->set_organization("Business Co");

Then we save them to some stream:

ostringstream out;
save_obj(e, out);
save_obj(c, out);

And finally use that stream to load those objects:

string data = out.str();

istringstream in(data);

boost::mixin::object obj1, obj2;
load_obj(obj1, in); // loading Alice
load_obj(obj2, in); // loading Bob

Now, let's see what we need to do to make the code from above work as expected.

First let's write the save function.

To save the object we'll need to write the names of its mixins. You might know that mixins also have id-s, but saving id-s is not a safe operation as they are generated based on the global instantiation order. This means that different programs with the same mixins (like a client or a server), or even the same program after a recompilation, could end up generating different id-s for the same mixins.

To get the names of the mixins in an object we could use object::get_mixin_names and it's perfectly fine, but in order to make this example a bit more interesting, let's dive a bit into the library's internal structure.

If you've read the implementation notes or the debugging tutorial, you'll know that an object has a type information member which contains the mixin composition of the object in a std::vector called _compact_mixins. We'll use this vector to save the mixin names.

size_t num_mixins = obj._type_info->_compact_mixins.size();
out << num_mixins << endl; // write the size
for(size_t i=0; i<num_mixins; ++i)
{
    // write each name
    out << obj._type_info->_compact_mixins[i]->name << endl;
}

After we've stored the object type information, we can now save the data within its mixins via the save message from above.

save(obj, out);

That was it. Now let's move to the code of the load_obj function.

First we need to get the number of mixins we're loading. Let's do it in this simple fashion:

string line;
getline(in, line);

size_t num_mixins = atoi(line.c_str());

Now we'll create an object_type_template which we'll use to store the loaded type and give it to a new object. The type template class (as all other mutator classes) has the method add. Besides the way you're used to calling it – add<mixin>() – you can also call it with a const char* argument, which will be interpreted as a mixin name.

When being called like this, it will return bool. True if a mixin of this name was found, and false if it wasn't. Note that this true or false value does not give you the information on whether the mixin will be added or removed from the object, but only a mixin of name exists in the domain. As you might remember the mutation rules (if such are added) will determine whether the mixin is actually added an removed.

boost::mixin::object_type_template tmpl;
for(size_t i=0; i<num_mixins; ++i)
{
    getline(in, line);
    tmpl.add(line.c_str());
}
tmpl.create();

Now what's left is to apply the template to the object:

tmpl.apply_to(obj);

The last thing we need to do when loading an object is to load the data within its mixins. The object is created with the appropriate mixins, so let's call the load multicast message.

load(obj, in);

It should load the data correctly because the order of the save and load execution is the same – determined by their priority.

Here are some explanations that may help you make sense of the code of the library if you need to read it:

The overall structure of the library is based on a main class called domain which holds all registered mixins and messages, and keeps the type registry.

Many people, upon seeing Boost.Mixin for the first time, have expressed a concern with the seemingly excessive amount of macros the library's users are required to write.