| Home | Libraries | People | FAQ | More

## Tutorial

### align

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();
      }
    }

### aligned_alloc and aligned_free

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);
      }
    }

### aligned_allocator

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());
    }

### aligned_allocator_adaptor

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;
    }

### aligned_delete

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;
      }
    }

### alignment_of

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;
    }

### assume_aligned

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);
    }

### is_aligned

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);
    }