163 строки
6.2 KiB
C
163 строки
6.2 KiB
C
/*
|
|
* Copyright (c) 2004-2007 The Trustees of Indiana University and Indiana
|
|
* University Research and Technology
|
|
* Corporation. All rights reserved.
|
|
* Copyright (c) 2004-2006 The University of Tennessee and The University
|
|
* of Tennessee Research Foundation. All rights
|
|
* reserved.
|
|
* Copyright (c) 2004-2005 High Performance Computing Center Stuttgart,
|
|
* University of Stuttgart. All rights reserved.
|
|
* Copyright (c) 2004-2005 The Regents of the University of California.
|
|
* All rights reserved.
|
|
* $COPYRIGHT$
|
|
*
|
|
* Additional copyrights may follow
|
|
*
|
|
* $HEADER$
|
|
*/
|
|
|
|
/**
|
|
* @file@
|
|
*
|
|
* Hooks for receiving callbacks when memory is allocated or deallocated
|
|
*
|
|
* Hooks for receiving callbacks when memory is allocated or
|
|
* deallocated from the current process. Intended to be used with
|
|
* RDMA communication devices that require "pinning" of virtual
|
|
* memory. The hooks allow for a "lazy unpinning" approach, which
|
|
* provides better latency when application buffer reuse is high.
|
|
* Most operating systems do not respond well to memory being freed
|
|
* from a process while still pinned, so some type of callback to
|
|
* unpin is necessary before the memory is returned to the OS.
|
|
*
|
|
* \note For linking reasons, this is not a component framework (some of
|
|
* these require tight coupling into libopal and the wrapper compilers
|
|
* and that entire stack).
|
|
*/
|
|
|
|
#ifndef OPAL_MEMORY_MEMORY_H
|
|
#define OPAL_MEMORY_MEMORY_H
|
|
|
|
#include "opal_config.h"
|
|
#include "memory_internal.h"
|
|
|
|
BEGIN_C_DECLS
|
|
|
|
|
|
/**
|
|
* Initialize the memory hooks subsystem
|
|
*
|
|
* Initialize the memory hooks subsystem. This is generally called
|
|
* during opal_init() and should be called before any other function
|
|
* in the interface is called.
|
|
*
|
|
* \note Note that some back-end functionality is activated pre-main,
|
|
* so not calling this function does not prevent the memory hooks from
|
|
* becoming active.
|
|
*
|
|
* @retval OPAL_SUCCESS Initialization completed successfully
|
|
*/
|
|
OPAL_DECLSPEC int opal_mem_hooks_init(void);
|
|
|
|
|
|
/**
|
|
* Finalize the memory hooks subsystem
|
|
*
|
|
* Finalize the memory hooks subsystem. This is generally called
|
|
* during opal_finalize() and no other memory hooks functions should
|
|
* be called after this function is called. opal_mem_hooks_finalize()
|
|
* will automatically deregister any callbacks that have not already
|
|
* been deregistered. In a multi-threaded application, it is possible
|
|
* that one thread will have a memory hook callback while the other
|
|
* thread is in opal_mem_hooks_finalize(), however, no threads will
|
|
* receive a callback once the calling thread has exited
|
|
* opal_mem_hooks_finalize().
|
|
*
|
|
* @retval OPAL_SUCCESS Shutdown completed successfully
|
|
*/
|
|
OPAL_DECLSPEC int opal_mem_hooks_finalize(void);
|
|
|
|
|
|
/**
|
|
* Query level of support provided by memory hooks
|
|
*
|
|
* Query memory hooks subsystem about the level of support provided by
|
|
* the current system configuration. The return value is \c 0 if no
|
|
* support is provided or a bit-wise OR of the available return values
|
|
* if support is provided.
|
|
*
|
|
* @retval OPAL_MEMORY_FREE_SUPPORT Memory hooks subsytem can trigger
|
|
* callback events when memory is going
|
|
* to be released by the process, either
|
|
* by the user calling an allocator
|
|
* function or munmap. Implies
|
|
* OPAL_MEMORY_MUNMAP_SUPPORT.
|
|
* @retval OPAL_MEMORY_MUNMAP_SUPPORT Subsystem can trigger callback events
|
|
* by the user calling munmap directly.
|
|
* @retval OPAL_MEMORY_CHUNK_SUPPORT Memory hooks subsystem will only
|
|
* trigger callback events when the
|
|
* process is giving memory back to the
|
|
* operating system, not at ever call
|
|
* to realloc/free/etc.
|
|
*
|
|
* \note This function must be called after opal_mem_hooks_init().
|
|
*/
|
|
OPAL_DECLSPEC int opal_mem_hooks_support_level(void);
|
|
|
|
|
|
/**
|
|
* Memory status change callback
|
|
*
|
|
* Typedef for callbacks triggered when memory has been allocated or
|
|
* is about to be freed. The callback will be triggered according to
|
|
* the note in opal_mem_hooks_register_alloc() or
|
|
* opal_mem_hooks_register_release().
|
|
*
|
|
* @param buf Pointer to the start of the allocation
|
|
* @param lentgh Length of the allocation
|
|
* @param cbdata Data passed to memory hooks when callback
|
|
* was registered
|
|
* @param from_alloc True if the callback is caused by a call to the
|
|
* general allocation routines (malloc, calloc, free,
|
|
* etc.) or directly from the user (mmap, munmap, etc.)
|
|
*/
|
|
typedef void (opal_mem_hooks_callback_fn_t)(void *buf, size_t length,
|
|
void *cbdata, bool from_alloc);
|
|
|
|
|
|
/**
|
|
* Register callback for when memory is to be released
|
|
*
|
|
* Register a \c opal_mem_hooks_callback_fn_t function pointer to be called
|
|
* whenever the current process is about to release memory.
|
|
*
|
|
* @param func Function pointer to call when memory is to be released
|
|
* @param cbdata A pointer-length field to be passed to func when it is
|
|
* invoked.
|
|
*
|
|
* @retval OPAL_SUCCESS The registration completed successfully.
|
|
* @retval OPAL_EXISTS The function is already registered and will not
|
|
* be registered again.
|
|
* @retval OPAL_ERR_NOT_SUPPORTED There are no hooks available for
|
|
* receiving callbacks when memory is to be released
|
|
*/
|
|
OPAL_DECLSPEC int opal_mem_hooks_register_release(opal_mem_hooks_callback_fn_t *func,
|
|
void *cbdata);
|
|
|
|
/**
|
|
* Unregister previously registered release callback
|
|
*
|
|
* Unregister previously registered release callback.
|
|
*
|
|
* @param func Function pointer to registered callback to remove
|
|
*
|
|
* @retval OPAL_SUCCESS The function was successfully deregistered
|
|
* @retval OPAL_ERR_NOT_FOUND The function was not previously registered
|
|
*/
|
|
OPAL_DECLSPEC int opal_mem_hooks_unregister_release(opal_mem_hooks_callback_fn_t *func);
|
|
|
|
|
|
END_C_DECLS
|
|
|
|
#endif /* OPAL_MEMORY_MEMORY_H */
|