Pointer liberation party (PLP)

Table of contents

• Introduction
• Features
• API Overview
• Core Concepts
• Detailed Functionality
• Usage Guidelines
• Customization
• Compilation and Testing

Introduction

This project focuses on developing a custom manual memory management library for C programs. This library utilizes reference counting, safe deallocation, and memory efficiency. It includes features to prevent common memory errors such as dangling pointers, multiple deallocations, and memory leaks. The functions provided by this library replaces traditional memory management functions as malloc, calloc and free with custom implementations tracking useful meta data about allocated memory objects. The library supports custom destructors to handle resource cleanup and incorporates default destructors for automating object deconstruction. To counteract performance issues, a cascade limit restricts how many objects are freed at once, this limit is currently 500.

Features

• Reference Counting:

  Automatically tracks the usage of allocated objects to determine when they can be safely deallocated.

• Destructor Functions:

  Allows custom cleanup logic for complex data structures.

• Default Destructor:

  Cleans up referenced objects automatically when no custom destructor is provided.

• Cascade Deallocation:

  Ensures efficient cleanup of multiple objects while avoiding excessive memory operations.

• Memory Safety:

  Prevents double-free and use-after-free errors with robust metadata management.

API Overview

These are the provided functions of this library categorized.

Function descriptions can be found in the refmem.h file and some further down in this document.

Memory Allocation and Deallocation

obj *allocate(size_t bytes, function1_t destructor)
obj *allocate_array(size_t elements, size_t elem_size, function1_t destructor)
void deallocate(obj *o)

Reference Management functions

void retain(obj *o)
void release(obj *o)
size_t rc(obj *o)

Cleanup and Limits

void cleanup()
void shutdown()
void set_cascade_limit(size_t limit)
size_t get_cascade_limit()

Core Concepts

Reference Counting

Each allocated object has a metadata structure tracking its reference count (rc). When the reference count reaches zero, the object is eligible for deallocation.

Destructor Functions

Custom destructors allow proper cleanup of nested or dynamic data structures. If no custom destructor is specified, a default one recursively releases referenced objects.

Cascade Deallocation

Objects with zero reference counts are queued for deallocation to avoid deep recursive calls or excessive processing in a single step. A cascade limit (500) controls the maximum number of objects deallocated at once.

Detailed Functionality

Memory Allocation

The allocate and allocate_array functions allocate memory for objects and associate them with metadata, including reference counts and destructors.

Reference Management

• retain:

  Increases the reference count of an object.

• release:

  Decreases the reference count and deallocates the object when the count reaches zero.

Cleanup

The cleanup function iterates over all objects, deallocating those with zero references. It ensures memory is cleaned up in a safe and controlled manner.

Cascade Limit

To prevent excessive memory operations, the library limits the number of objects deallocated in a single cascade. This limit can be configured using set_cascade_limit.

Usage Guidelines

• Initialize Objects: Use allocate or allocate_array to create objects and specify custom destructors if needed.
• Manage References: Use retain and release to manage the lifecycle of objects.
• Clean Up: Call cleanup periodically to deallocate unused objects.
• Shutdown Safely: Use shutdown to reset the library's internal state before program termination.

Customization

• Custom Destructors: Define destructor functions tailored to your use case.
• Cascade Limit: Adjust the cascade deallocation limit to optimize performance for your use case.

Compilation and Testing

Prerequisites

• GCC: Ensure gcc is installed on your system.
• CUnit: Required for unit testing. Install it if not already available.
• Valgrind: Required for memory leak tests.
• LCOV and genhtml: Required for generating coverage reports.

Targets Overview

1. Build the Project

   This command compiles the src/refmem.c file into an object file (obj/refmem.o).

   make all

2. Run the Main Program

   Compiles and links src/main.c and src/refmem.c to produce an executable obj/main.out. Executes the program.

   make run

3. Check for Memory Leaks

   Runs the main program under Valgrind to check for memory leaks.

   make memrun

4. Run Unit Tests

   Compiles and links the test files (test/test.c and src/refmem.c) into obj/test.out. Executes the unit tests.

   make test

5. Check Memory in Unit Tests

   Runs the unit tests under Valgrind to check for memory leaks during testing.

   make memtest

6. Generate Code Coverage

   Compiles test/test.c and src/refmem.c with coverage flags enabled. Runs the tests and captures code coverage data using LCOV. Generates an HTML coverage report in ./obj/coverage.

   make covtest

7. Clean Up

   Removes all object files, executables, and generated coverage files in the obj/ directory.

   make clean

8. Demo

   Compiles the the demo with the garbage collector and generates an executable in demo/obj

   make demo