AllocMem Function Documentation

Overview

The AllocMem function is a custom memory allocation utility designed to provide flexible and robust memory management across various memory types, data types, and computing environments. It supports heap, stack, IPC, GPU, cloud, registry, and page memory, with fine-grained control over data types, array dimensions, and memory attributes.

The function is built to handle both simple allocations (similar to malloc) and complex, metadata-driven allocations via a MemoryAllocationRequest structure, making it suitable for applications ranging from embedded systems to high-performance computing.

Functionality

The AllocMem function allocates memory with customizable properties and returns a pointer to the allocated memory. It supports two modes of operation:

• Simple Allocation: Allocate memory of a specified size using a default heap-based approach.
• Advanced Allocation: Use a MemoryAllocationRequest structure to specify memory type, data type, array dimensions, and additional flags.

Signature

void* AllocMem(uint64_t tSize, ...)

Parameters

Return Value

• Success: Pointer to the allocated memory (payload starts after a MemoryHandle structure).
• Failure: NULL if allocation fails or input is invalid.

Versatility

The AllocMem function is highly versatile, making it suitable for a wide range of use cases. Its flexibility stems from the following features:

1. Multiple Memory Types

Supports allocation across diverse memory types, enabling compatibility with different hardware and software environments:

• HEAP_MEMORY: Standard heap memory for general-purpose use.
• STACK_MEMORY: Simulates stack-like allocation behavior.
• IPC_MEMORY: Memory for inter-process communication.
• GPU_MEMORY: GPU-accessible memory for graphics or parallel computing.
• CLOUD_MEMORY: Memory for distributed or cloud-based systems.
• REGISTRY_MEMORY: Memory for persistent storage or configuration.
• PAGE_MEMORY: Memory mapped to virtual memory pages.
• RESERVED_MEMORY: Reserved for future or custom use.

This allows AllocMem to be used in embedded systems, high-performance computing, distributed systems, and GPU-accelerated applications.

2. Flexible Data Types

Supports a variety of data types, from primitive types to complex objects:

• DATA_BYTE, DATA_SHORT, DATA_CHAR, DATA_INT, DATA_LONG, DATA_FLOAT, DATA_DOUBLE: Standard primitive types.
• DATA_OBJECT: Custom or complex data structures.

Additionally, the DATA_SIGNED flag allows specification of signedness for primitives, and DATA_CONTAINED supports encapsulated objects.

3. Array Dimension Support

Handles multi-dimensional arrays with explicit dimension encoding:

• DATA_PRIMITIVE: Single value.
• DATA_ARRAY: 1D array.
• DATA_2D_ARRAY: 2D array.
• DATA_3D_ARRAY: 3D array.

This is particularly useful for scientific computing, image processing, or machine learning applications requiring multi-dimensional data structures.

4. Advanced Memory Flags

Provides fine-grained control over memory behavior through flags:

• MEMORY_STORE: Indicates memory should be stored persistently.
• MEMORY_RESIDENT: Saves memory state on program exit.
• MEMORY_ALLOCATED: Marks memory as allocated (e.g., mapped for page memory).
• MEMORY_LOG_ACCESS: Enables access logging for debugging or auditing.
• MEMORY_NAME_UNICODE: Supports Unicode memory names.
• GPU-specific flags like MEMORY_GPU_GLOBAL, MEMORY_GPU_SHARED, MEMORY_GPU_TEXTURE, and MEMORY_GPU_LOCAL for GPU memory management.

5. Packed Parameters

The DATA_PACK_PARAMETERS flag allows optimized storage of parameters, reducing memory overhead in specific use cases, such as parameter passing in distributed systems.

6. Memory Auditing and Naming

Automatically generates unique Unicode names for memory blocks if not provided, and integrates with a MemoryHandle structure for tracking allocation metadata (e.g., size, creation time, last access). Memory allocations are added to a memory list for auditing, enhancing debugging and resource management.

7. Cross-Platform Compatibility

By abstracting memory types and providing a unified interface, AllocMem can be adapted to different platforms, from CPUs to GPUs, and from local systems to cloud environments.

This versatility makes AllocMem a powerful tool for developers working on complex systems requiring precise control over memory allocation and management.

Usage Examples

Simple Allocation

Allocate 1024 bytes of heap memory:

void* ptr = AllocMem(1024);
if (ptr) {
    // Use memory
    // Memory is automatically named (e.g., "user_mem1")
}

Advanced Allocation

Allocate a 2D array of signed integers in GPU memory:

struct MemoryAllocationRequest request = {
    .ma_size = 1024 * sizeof(int),
    .ma_ram_type = GPU_MEMORY,
    .ma_data_type = DATA_INT | DATA_SIGNED,
    .ma_dimension_type = DATA_2D_ARRAY,
    .ma_flags = MEMORY_GPU_GLOBAL,
    .ma_name = L"gpu_int_array"
};
void* ptr = AllocMem(0xffffffffffffffff, &request);
if (ptr) {
    // Use GPU-accessible 2D integer array
}

Error Handling

Check for allocation failure:

void* ptr = AllocMem(0); // Invalid size
if (!ptr) {
    printf("Allocation failed: Invalid size\n");
}

Encoding Scheme

The AllocMem function uses a compact encoding scheme to store metadata about memory allocations. The encoding is managed through bit fields and decoded using the DECODE_CHANNEL_DATA macro.

Key Macros

Decoding Example

uint8_t memoryType, primitiveType, dimensionBits, packedParameters, isSigned;
int64_t input = (DATA_PACK_PARAMETERS << 24) | (DATA_2D_ARRAY << 16) | (DATA_INT << 8) | GPU_MEMORY;
DECODE_CHANNEL_DATA(input, memoryType, primitiveType, dimensionBits, packedParameters, isSigned);
// Results:
// memoryType = GPU_MEMORY
// primitiveType = DATA_INT
// dimensionBits = DATA_2D_ARRAY
// packedParameters = 1
// isSigned = 0