src/dw/core/docs/usecase3.md

Go to the documentation of this file.

# Copyright (c) 2019-2020, NVIDIA CORPORATION.  All rights reserved.

@page core_usecase3 Memory Management Policies and Multithreading
@tableofcontents

The NVIDIA<sup>&reg;</sup> DriveWorks memory management policy defines conventions intended to protect modules from memory corruption during runtime.

@section core_memorymanagement Memory Management

For modules that require memory, the preferred method is static allocation (on
the stack). When that is not possible, memory allocation is controlled with
these conventions:
- During initialization/creation, modules use a _memory allocator_ to
  dynamically allocate memory (on the heap). DriveWorks provides a default memory
  allocator; however, you can also supply your own custom memory allocator. See
  @ref core_mm_customallocators (below) and @ref core_memory_group.
- Memory allocator APIs allocate dynamic memory only during initialization time (before
  runtime mode begins). With this restriction, dynamic memory allocation provides
  similar protections to static memory allocation.

@subsection core_mm_customallocators Using Custom Memory Allocators

Before initializing a context, you can pass an instance of a custom memory
allocator to the SDK. The SDK then uses the memory allocator to perform dynamic
memory allocations.

@note SDK modules do perform dynamic allocations
only during initialization/creation time and perform no allocations at runtime.

```{.cpp}
#include <dw/core/DynamicMemory.h>

// setup memory allocator
dwDynamicMemory_initialize(myMalloc, myFree, myContext);

// initialize SDK

dwInitialize(&sdkContext, DW_VERSION, &contextParams);

...
// do processing
...

// release SDK context
dwRelease(&sdkContext);

// release memory allocator
dwDynamicMemory_release();

```

@note As of this release, the user allocator is global. As such, it is not bound to a specific SDK context.

@section core_threadsafety Thread Safety

Currently, the methods that DriveWorks modules expose do not follow any thread-
safety paradigm. To avoid the overhead of memory locks, DriveWorks methods are
considered to be non-thread safe. The exceptions are methods with documentation
that explicitly indicate a thread-safe implementation.

Applications are responsible for implementing thread-safety, if such is
required.