/* * 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 "memory_internal.h" #if defined(c_plusplus) || defined(__cplusplus) extern "C" { #endif /** * 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 mmap. * @retval OPAL_MEMORY_MALLOC_SUPPORT Memory hooks subsystem can trigger * callback events when memory is being * allocated by the process through the * traditional allocator (malloc, * calloc, etc.) * @retval OPAL_MEMORY_MMAP_SUPPORT Memory hooks subsystem can trigger * callback events when memory is being * allocated by the process through mmap. * @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 malloc/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 has been allocated * * Register a \c opal_mem_hooks_callback_fn_t function pointer to be * called whenever the current process has allocated memory * * @param func Function pointer to call when memory has been allocated * @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 allocated */ OPAL_DECLSPEC int opal_mem_hooks_register_alloc(opal_mem_hooks_callback_fn_t *func, void *cbdata); /** * 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 alloc callback * * Unregister previously registered alloc 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_alloc(opal_mem_hooks_callback_fn_t *func); /** * 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); #if defined(c_plusplus) || defined(__cplusplus) } #endif #endif /* OPAL_MEMORY_MEMORY_H */