ae.sys.data

Wrappers for raw data located in unmanaged memory.

Using the Data type will only place a small object in managed memory, keeping the actual data in unmanaged memory. A proxy class (DataWrapper) is used to safely allow multiple references to the same block of unmanaged memory. When the DataWrapper object is destroyed (either manually or by the garbage collector when there are no remaining Data references), the unmanaged memory is deallocated.

This has the following advantage over using managed memory:

  • Faster allocation and deallocation, since memory is requested from the OS directly as whole pages
  • Greatly reduced chance of memory leaks (on 32-bit platforms) due to stray pointers
  • Overall improved GC performance due to reduced size of managed heap
  • Memory is immediately returned to the OS when data is deallocated

On the other hand, using Data has the following disadvantages:

  • This module is designed to store raw data which does not have any pointers. Storing objects containing pointers to managed memory is unsupported, and may result in memory corruption.
  • Small objects may be stored inefficiently, as the module requests entire pages of memory from the OS. Considering allocating one large object and use slices (Data instances) for individual objects.
  • Incorrect usage (i.e. retaining/escaping references to wrapped memory without keeping a reference to its corresponding DataWrapper) can result in dangling pointers and hard-to-debug memory corruption.

Public Imports

ae.sys.dataset
public import ae.sys.dataset;

Members

Classes

DataWrapper
class DataWrapper

Base abstract class which owns a block of memory.

Functions

setGCThreshold
void setGCThreshold(size_t value)

Set threshold of allocated memory to trigger a garbage collection.

unmanagedDelete
void unmanagedDelete(C c)

Delete a class instance created with unmanagedNew.

unmanagedNew
C unmanagedNew(Args args)

Allocate and construct a new class in malloc'd memory.

Static variables

allocCount
uint allocCount;

How many allocations have been done so far.

dataCount
uint dataCount;

How many DataWrapper instances there are live currently.

dataMemory
size_t dataMemory;

How many bytes are currently in Data-owned memory.

dataMemoryPeak
size_t dataMemoryPeak;

How many bytes are currently in Data-owned memory.

Structs

Data
struct Data

Wrapper for data located in external memory, to prevent faux references. Represents a slice of data, which may or may not be in unmanaged memory. Data in unmanaged memory is bound to a DataWrapper class instance.

Meta

License

This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/.

Authors

Vladimir Panteleev <ae@cy.md>