handle.h File Reference

Module for managing pointers using handles. More...

Go to the source code of this file.

Macros
#define	HANDLE_NULL   (0)

Functions
void	Handle_Reset ()
	Resets the handle management table.
void	Handle_Dump ()
	Dumps the contents of the handle management table.
u32	Handle_Entry (void *pPtr)
	Registers a pointer and returns a handle.
void *	Handle_GetPointer (u32 hdl)
	Retrieves a pointer from a handle.
bool	Handle_IsAlive (u32 hdl)
	Checks if a handle is valid.
void	Handle_Remove (u32 hdl)
	Removes a handle and frees the associated pointer.

Detailed Description

Module for managing pointers using handles.

This module provides functions to manage pointers using handles. It allows accessing pointers through handles, checking the validity of handles, and removing handles. This is particularly useful for dynamic memory management and resource management.

This module is provided as a helper for lower-level functions of cobj. While users can use it directly, it is neither recommended nor mandatory.

Note: This module is not thread-safe. Use appropriate synchronization mechanisms if accessing it from multiple threads.

Features

• Handle_Reset: Resets the handle management table.
• Handle_Dump: Dumps the contents of the handle management table.
• Handle_Entry: Registers a pointer and returns a handle.
• Handle_GetPointer: Retrieves a pointer from a handle.
• Handle_IsAlive: Checks if a handle is valid.
• Handle_Remove: Removes a handle and frees the associated pointer.

Usage Example

Here is an example of how to use this module to manage pointers with handles:

#include "handle.h"
#include <stdio.h>
#include <stdlib.h>
 
int main() {
    // Reset the handle management table
    Handle_Reset();
 
    // Allocate memory on the heap, register the pointer, and get a handle
    int* pHeap = (int*)malloc(sizeof(int));
    if (pHeap == NULL) {
        perror("Failed to allocate memory");
        return 1;
    }
    *pHeap = 10;
    u32 handle = Handle_Entry(pHeap);
    printf("Handle: %u\n", handle);
 
    // Retrieve the pointer from the handle
    int* p = (int*)Handle_GetPointer(handle);
    if (p) {
        printf("Value: %d\n", *p);
    } else {
        printf("Pointer not found\n");
    }
 
    // Check if the handle is valid
    if (Handle_IsAlive(handle)) {
        printf("Handle is alive\n");
    } else {
        printf("Handle is not alive\n");
    }
 
    // Free the pointer and remove the handle
    free(p); // Free the pointer before removing the handle
    Handle_Remove(handle);
 
    // Check that the handle has been successfully removed
    if (!Handle_IsAlive(handle)) {
        printf("Handle successfully removed\n");
    } else {
        printf("Handle removal failed\n");
    }
 
    return 0;
}

Version

1.0

Date

2024

Function Documentation

Handle_Dump()

void Handle_Dump ( )

extern

Dumps the contents of the handle management table.

This function dumps the contents of the handle management table, displaying all valid entries.

Handle_Entry()

u32 Handle_Entry ( void * pPtr )

extern

Registers a pointer and returns a handle.

This function registers a pointer and returns a handle that can be used to access the pointer.

Parameters

pPtr	Pointer to be registered.

Returns

Handle corresponding to the registered pointer.

Handle_GetPointer()

void * Handle_GetPointer ( u32 hdl )

extern

Retrieves a pointer from a handle.

This function retrieves the pointer associated with the given handle.

Parameters

hdl	Handle to be used to retrieve the pointer.

Returns

Pointer associated with the handle, or NULL if the handle is invalid.

Handle_IsAlive()

bool Handle_IsAlive ( u32 hdl )

extern

Checks if a handle is valid.

This function checks if the given handle is valid and has an associated pointer.

Parameters

hdl	Handle to be checked.

Returns

true if the handle is valid, false otherwise.

Handle_Remove()

void Handle_Remove ( u32 hdl )

extern

Removes a handle and frees the associated pointer.

This function removes the given handle and frees the memory associated with the pointer.

Parameters

hdl	Handle to be removed.

Handle_Reset()

void Handle_Reset ( )

extern

Resets the handle management table.

This function resets the handle management table, initializing all entries and resetting the next handle to be used.