root/opal/memoryhooks/memory.h

/* [<][>][^][v][top][bottom][index][help] */

INCLUDED FROM


   1 /* -*- Mode: C; c-basic-offset:4 ; indent-tabs-mode:nil -*- */
   2 /*
   3  * Copyright (c) 2004-2007 The Trustees of Indiana University and Indiana
   4  *                         University Research and Technology
   5  *                         Corporation.  All rights reserved.
   6  * Copyright (c) 2004-2006 The University of Tennessee and The University
   7  *                         of Tennessee Research Foundation.  All rights
   8  *                         reserved.
   9  * Copyright (c) 2004-2005 High Performance Computing Center Stuttgart,
  10  *                         University of Stuttgart.  All rights reserved.
  11  * Copyright (c) 2004-2005 The Regents of the University of California.
  12  *                         All rights reserved.
  13  * Copyright (c) 2018      Triad National Security, LLC. All rights
  14  *                         reserved.
  15  * $COPYRIGHT$
  16  *
  17  * Additional copyrights may follow
  18  *
  19  * $HEADER$
  20  */
  21 
  22 /**
  23  * @file@
  24  *
  25  * Hooks for receiving callbacks when memory is allocated or deallocated
  26  *
  27  * Hooks for receiving callbacks when memory is allocated or
  28  * deallocated from the current process.  Intended to be used with
  29  * RDMA communication devices that require "pinning" of virtual
  30  * memory.  The hooks allow for a "lazy unpinning" approach, which
  31  * provides better latency when application buffer reuse is high.
  32  * Most operating systems do not respond well to memory being freed
  33  * from a process while still pinned, so some type of callback to
  34  * unpin is necessary before the memory is returned to the OS.
  35  *
  36  * \note For linking reasons, this is not a component framework (some of
  37  * these require tight coupling into libopal and the wrapper compilers
  38  * and that entire stack).
  39  */
  40 
  41 #ifndef OPAL_MEMORY_MEMORY_H
  42 #define OPAL_MEMORY_MEMORY_H
  43 
  44 #include "opal_config.h"
  45 #include "memory_internal.h"
  46 
  47 BEGIN_C_DECLS
  48 
  49 
  50 /**
  51  * Initialize the memory hooks subsystem
  52  *
  53  * Initialize the memory hooks subsystem.  This is generally called
  54  * during opal_init() and should be called before any other function
  55  * in the interface is called.
  56  *
  57  * \note Note that some back-end functionality is activated pre-main,
  58  * so not calling this function does not prevent the memory hooks from
  59  * becoming active.
  60  *
  61  * @retval OPAL_SUCCESS Initialization completed successfully
  62  */
  63 OPAL_DECLSPEC int opal_mem_hooks_init(void);
  64 
  65 
  66 /**
  67  * Query level of support provided by memory hooks
  68  *
  69  * Query memory hooks subsystem about the level of support provided by
  70  * the current system configuration.  The return value is \c 0 if no
  71  * support is provided or a bit-wise OR of the available return values
  72  * if support is provided.
  73  *
  74  * @retval OPAL_MEMORY_FREE_SUPPORT   Memory hooks subsytem can trigger
  75  *                                    callback events when memory is going
  76  *                                    to be released by the process, either
  77  *                                    by the user calling an allocator
  78  *                                    function or munmap.  Implies
  79  *                                    OPAL_MEMORY_MUNMAP_SUPPORT.
  80  * @retval OPAL_MEMORY_MUNMAP_SUPPORT Subsystem can trigger callback events
  81  *                                    by the user calling munmap directly.
  82  * @retval OPAL_MEMORY_CHUNK_SUPPORT  Memory hooks subsystem will only
  83  *                                    trigger callback events when the
  84  *                                    process is giving memory back to the
  85  *                                    operating system, not at ever call
  86  *                                    to realloc/free/etc.
  87  *
  88  * \note This function must be called after opal_mem_hooks_init().
  89  */
  90 OPAL_DECLSPEC int opal_mem_hooks_support_level(void);
  91 
  92 
  93 /**
  94  * Memory status change callback
  95  *
  96  * Typedef for callbacks triggered when memory has been allocated or
  97  * is about to be freed.  The callback will be triggered according to
  98  * the note in opal_mem_hooks_register_alloc() or
  99  * opal_mem_hooks_register_release().
 100  *
 101  * @param buf     Pointer to the start of the allocation
 102  * @param lentgh  Length of the allocation
 103  * @param cbdata  Data passed to memory hooks when callback
 104  *                was registered
 105  * @param from_alloc True if the callback is caused by a call to the
 106  *                general allocation routines (malloc, calloc, free,
 107  *                etc.) or directly from the user (mmap, munmap, etc.)
 108  */
 109 typedef void (opal_mem_hooks_callback_fn_t)(void *buf, size_t length,
 110                                             void *cbdata, bool from_alloc);
 111 
 112 
 113 /**
 114  * Register callback for when memory is to be released
 115  *
 116  * Register a \c opal_mem_hooks_callback_fn_t function pointer to be called
 117  * whenever the current process is about to release memory.
 118  *
 119  * @param func    Function pointer to call when memory is to be released
 120  * @param cbdata  A pointer-length field to be passed to func when it is
 121  *                invoked.
 122  *
 123  * @retval OPAL_SUCCESS The registration completed successfully.
 124  * @retval OPAL_EXISTS  The function is already registered and will not
 125  *                      be registered again.
 126  * @retval OPAL_ERR_NOT_SUPPORTED There are no hooks available for
 127  *                      receiving callbacks when memory is to be released
 128  */
 129 OPAL_DECLSPEC int opal_mem_hooks_register_release(opal_mem_hooks_callback_fn_t *func,
 130                                                   void *cbdata);
 131 
 132 /**
 133  * Unregister previously registered release callback
 134  *
 135  * Unregister previously registered release callback.
 136  *
 137  * @param func   Function pointer to registered callback to remove
 138  *
 139  * @retval OPAL_SUCCESS The function was successfully deregistered
 140  * @retval OPAL_ERR_NOT_FOUND The function was not previously registered
 141  */
 142 OPAL_DECLSPEC int opal_mem_hooks_unregister_release(opal_mem_hooks_callback_fn_t *func);
 143 
 144 
 145 END_C_DECLS
 146 
 147 #endif /* OPAL_MEMORY_MEMORY_H */

/* [<][>][^][v][top][bottom][index][help] */