Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is the documentation for an old version of boost. Click here for the latest Boost documentation.
PrevUpHomeNext

Tutorial

align
aligned_alloc and aligned_free
aligned_allocator
aligned_allocator_adaptor
aligned_delete
alignment_of
assume_aligned
is_aligned

The alignment function can be used to find the first address of a given alignment value within a given buffer of a given size. It adjusts the pointer provided, returns that value, and decreases space by the amount advanced, if the alignment succeeds, provided sufficient space in the buffer. Otherwise it yields a null pointer to indicate failure due to insufficient space.

#include <boost/align/align.hpp>

template<class T>
inline T* make(void* ptr, std::size_t space)
{
  void* p = boost::alignment::align(alignof(T), sizeof(T), ptr, space);
  if (p) {
    return ::new(p) T();
  } else {
    return nullptr;
  }
}

struct alignas(16) type {
  float data[4];
};

int main()
{
  char c[48];
  type* p = make<type>(c, sizeof c);
  if (p) {
    p->~type();
  }
}

Consider these functions alignment enabled versions of std::malloc(std::size_t) and std::free(void*) or ::operator new(std::size_t, const std::no_throw_t&) and ::operator delete(void*). The aligned allocation function allocates space with the specified size and alignment. The aligned deallocation function can then deallocate this space.

#include <boost/align/aligned_alloc.hpp>

void use(void* ptr, std::size_t size)
{
  (void)ptr;
  (void)size;
}

int main()
{
  void* p = boost::alignment::aligned_alloc(16, 100);
  if (p) {
    use(p, 100);
    boost::alignment::aligned_free(p);
  }
}

Consider this class template a superior version of the default allocator, std::allocator, because it can be used with types that are over-aligned.

#include <boost/align/aligned_allocator.hpp>
#include <vector>

struct alignas(16) type {
  float data[4];
};

void use(type* ptr, std::size_t size)
{
  (void)ptr;
  (void)size;
}

int main()
{
  std::vector<type, boost::alignment::aligned_allocator<type> > v(100);
  use(&v[0], v.size());
}

The optional template parameter of this class allows specifying a minimum alignment to use for allocations. The default minimum alignment is 1.

#include <boost/align/aligned_allocator.hpp>
#include <vector>

void use(char* ptr, std::size_t size)
{
  (void)ptr;
  (void)size;
}

int main()
{
  std::vector<char,
    boost::alignment::aligned_allocator<char, 16> > v(100);
  use(&v[0], v.size());
}

This class template can turn any existing allocator type, C++11 or C++03, stateful or stateless, into one that supports types which are over-aligned.

#include <boost/align/aligned_allocator_adaptor.hpp>
#include <vector>

template<class T, class Allocator>
class utility {
public:
  utility(std::size_t size)
    : v(size) {
  }
private:
  std::vector<T,
    boost::alignment::aligned_allocator_adaptor<Allocator> > v;
};

struct alignas(16) type {
  float data[4];
};

int main()
{
  utility<type, std::allocator<type> > u(100);
  (void)u;
}

The optional template parameter of this class allows specifying a minimum alignment to use for allocations. The default minimum alignment is 1.

#include <boost/align/aligned_allocator_adaptor.hpp>
#include <vector>

template<class T, class Allocator, std::size_t Alignment>
class utility {
public:
  utility(std::size_t size)
    : v(size) {
  }
private:
  std::vector<T, boost::alignment::
    aligned_allocator_adaptor<Allocator, Alignment> > v;
};

int main()
{
  utility<char, std::allocator<char>, 16> u(100);
  (void)u;
}

Consider this class an alignment aware version of the std::default_delete deleter class template. It is a deleter that destroys the object and then deallocates space using our aligned deallocation function. It should be used with constructed objects that were allocated with our aligned allocation function and is useful with deleter enabled types like std::unique_ptr.

#include <boost/align/aligned_delete.hpp>
#include <memory>

struct alignas(16) type {
  float data[4];
};

int main()
{
  void* p =
    boost::alignment::aligned_alloc(alignof(type), sizeof(type));
  if (p) {
    type* q = ::new(p) type();
    std::unique_ptr<type, boost::alignment::aligned_delete> u(q);
    (void)u;
  }
}

This type trait can be used to query the alignment requirement of a type at compile time. It is useful in static assertions to validate type alignment.

#include <boost/align/alignment_of.hpp>

template<class T>
class utility {
  static_assert(boost::alignment::alignment_of<T>::value == 16, "");
public:
  utility()
    : object() {
  }
private:
  T object;
};

struct alignas(16) type {
  float data[4];
};

int main()
{
  utility<type> u;
  (void)u;
}

This macro is used to notify the compiler of a given pointer variable's alignment. It is useful for guide optimizing compilers into vectorizing or applying other compiler specific, alignment related optimizations.

#include <boost/align/assume_aligned.hpp>

void use(double* array, std::size_t size)
{
  BOOST_ALIGN_ASSUME_ALIGNED(array, 64);
  for (std::size_t i = 0; i < size; i++) {
    array[i]++;
  }
}

int main()
{
  alignas(16) double d[4] { };
  use(f, 4);
}

This function is used to compare the alignment of a pointer. It is useful in assertions that validate a pointer value is aligned on a given boundary.

#include <boost/align/is_aligned.hpp>
#include <cassert>

void use(void* ptr, std::size_t size)
{
  assert(boost::alignment::is_aligned(ptr, 16));
  (void)size;
}

int main()
{
  alignas(16) char c[100];
  use(c, sizeof c);
}

PrevUpHomeNext