Introduction

Boxyto is a C++ 11, 14 library for real time and high performance applications that includes more of the standard library re-implemented, with many enhancements and new features. On the other hand, Boxyto showed much performance improvements in benchmarks regarding to standard library.

Boxyto is an excellent choise when you have very limited memory budget or low memory device available, and you already know how almost you application will going to consume, especially on Mobile and Console devices where memory is very tight.

Version

0.8.12

Features

• Cross platform (Windows - Mac OS X - IOS - Android - Linux)
• 32-bit & 64-bit support
• Rich Templete support
• Complete memory management system
• Memory defragmentation support
• Different container classes
• Containers iterators
• Easy to use and extend
• Memory Alignment support
• Smart Pointers
• Standard library interchange support
• OS detection
• Compiler support (MSVC - CLANG - GNU)

Classes & Modules

Memory Manager

• MemoryOps: Useful template functions for many pre-defined memory operations
• OSMemory: Operating system memory initializer and terminator
• StaticSegment: Segment manager for static allocations
• DynamicSegment: Segment manager for dynamic allocations, support defragmentation and other enhancments
• LinearAllocator: Allocator can be used with linear containers, such as Arrays
• PoolNodeAllocator: Allocator can be used with Node based containers, such as Linked Lists, with the idea of per-allocate capacity of nodes and recycling them
• FastNodeAllocator: Allocator used with StaticSegment, and can work with Node based containers
• SimpleNodeAllocator: Allocator used by Node based containers, this allocator allocate nodes on request
• Pointer: Different Pointer types to use with containers
• ShadredPointer: std::shadred_pointer like class
• UniquePointer: std::unique_pointer like class
• StdAllocator: Allocator to use with all std containers to consume boxyto memory manager
• PlatformMemory: Headers to use by system for memory on OS

Containers

Each container have iterators, search/find, and can input/output to other types of container

• Array: Dynamic array that can also simulate stack and queue operations
• DoubleLinkedList: Double Linked List of connected nodes, container also support stack and queue operations
• Map: Red-Black tree based map
• HashMap: key-value hashed map
• HashList: Hashed key list
• CircularArray: Static array the work like queue
• Pair: Key-Value pair
• Sets: Not a container, but a set of functions that apply Set opreations on any type of container
• ForEach: Simplified for each that iterate over a container elements, and execute a function on them

Templates

• Common: Some template based support for other systems

Usage

Using Memory manager

First, we need to initialize the memory manager:

using namespace Everest;

// Init memory manager
OSMemory::Init(SIZE_T size);

size, is the required size by the application for it's life-cycle, it's important to notice that all boxyto memory system depend on this.

When the application goes to end, we need to shutdown and release our memory manager:

// Shutdown memory manager
OSMemory::Terminate();

and that's it!

To use the memory manager, we need to create something called Segment Manager, and a segment is simply a segment of memory contains one or more system pages, the default page size is the huge system page size (most of time 2 MiB), witch is a TLB hit, you can query the system page size size by call

OSMemory::GetPageSize();

Segments are very big, we can directly use segments for allocations, or we can use allocators to direct interact with segments, here is an example:

// Create a dynamic segment
// note that pageCount is how many pages we need in this segment, 
// if left empty, that means one page (default)
DynamicSegment dynamicSegment(pageCount);

// Direct allocate from segment
// Alloc takes the allocation size, and allocation alignment (power of 2)
UINTPTR handle = dynamicSegment.Alloc(1024, 16);

// You can also use the _NEW<T> function to simulate the new opreator
UINTPTR handleNew = dynamicSegment._NEW<std::string>("Hey Boxytp!");

// We use a handle because our segment allows defragmentation, and this will change pointer location in memory
// To obtain a pointer at any time
void* ptr = DynamicSegment::PointerOf(handle);

// if you would like to obtain an updated pointer nomatter when it called, use Pointer<T> class
Pointer<T> ptr = DynamicSegment::PointerOf(handle);
ptr->DoSomething();
// OR...
ptr.Get()->DoSomething();

// To deallocate an allocation
dynamicSegment.Dealloc(handle);

// To defragment a dynamic segment
// remember that defragmentation is consuming time heavly, use it wisely,
// for example: use it when we have remaining time in our game loop system
dynamicSegment.Defragment();

// To reset/release a segment
dynamicSegment.Release();

Using Containers

We will assume that we have configured DynamicSegment, also we will use Everest::Array for example

// Define out allocator for simple
typedef Everest::LinearAllocator<std::string> Allocator;

// Create a segment manager to consume
// A segment with 1 page (default)
std::shard_ptr<DynamicSegment> segment(new DynamicSegment);

// Create an allocator instance
// allocators should constructed with a segment manager instance
Allocator alloc(segment);

// Create the array
// We then pass a configured allocator to the container
Everest::Array<std::string, Allocator> array(alloc);

// The following is wrong for all boxyto containers
// NO TEMPLATE ALLOCATOR TYPE!
// NO CONSTRUCTOR
// Everest::Array<std::string> array;

What if you would like to use boxyto memory manager with std containers?

No problem, use Everest::StdAllocator class:

// Define the allocator type
typedef Everest::Allocator<std::string> StdAllocType;

// Create the allocator
// Std allocators can consume static segments only
StdAllocType stdAlloc(staticSegment);

// Create a std vector container
// Do not fotget to construct with the allocator instance creator
// You can do the same steps for any std container
std::vector<std::string, StdAllocType> myVec(stdAlloc);

// Use your container as usual, 
// and now the container allocates from boxyto memory manager
// ...

Documentation

All source code is inline documented

Questions

Contact me with your suggestions and questions at: [email protected]

License

MIT

Free Software, Hell Yeah!