root/opal/mca/memory/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-2005 The Trustees of Indiana University and Indiana
   4  *                         University Research and Technology
   5  *                         Corporation.  All rights reserved.
   6  * Copyright (c) 2004-2005 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) 2009      Cisco Systems, Inc.  All rights reserved.
  14  * Copyright (c) 2015-2016 Los Alamos National Security, LLC. All rights
  15  *                         reserved.
  16  * Copyright (c) 2016      Research Organization for Information Science
  17  *                         and Technology (RIST). All rights reserved.
  18  * $COPYRIGHT$
  19  *
  20  * Additional copyrights may follow
  21  *
  22  * $HEADER$
  23  */
  24 
  25 /* NOTE: This framework accomodates two kinds of memory hooks systems:
  26 
  27    1. Those that only require being setup once and then will
  28       automatically call back to internal component/module functions
  29       as required (e.g., the ptmalloc2 component).  It is expected
  30       that such components will have a NULL value for memoryc_process
  31       and empty (base) implementations of memoryc_register and
  32       memoryc_deregister.
  33 
  34    2. Those that must be queried periodically to find out if something
  35       has happened to the registered memory mappings (e.g., the
  36       ummunot component).  It is expected that such components will
  37       have complete implementations for memoryc_process,
  38       memoryc_register, and memoryc_deregister.
  39 
  40    There will only be one of these components compiled in to Open MPI
  41    (it will be compiled in libopen-pal; it will never be a DSO).  so
  42    the componente will rule "yes, I can run" or "no, I cannot run".
  43    If it elects not to run, then there is no memory manager support in
  44    this process.
  45 
  46    Because there will only be one memory manager component in the
  47    process, there is no need for a separate module structure --
  48    everything is in the component for simplicity.
  49 
  50    Note that there is an interface relevant to this framework that is
  51    not described in this file: the opal_memory_changed() macro.  This
  52    macro should return 1 if an asynchronous agent has noticed that
  53    memory mappings have changed.  The macro should be as cheap/fast as
  54    possible (which is why it's a macro).  If it returns 1, the
  55    memoryc_process() function pointer (below), will be invoked.  If
  56    the component does not provide this macro, then a default macro is
  57    used that always returns 0 and therefore memoryc_process() will
  58    never be invoked (and can legally be NULL).
  59 */
  60 
  61 #ifndef OPAL_MCA_MEMORY_MEMORY_H
  62 #define OPAL_MCA_MEMORY_MEMORY_H
  63 
  64 #include "opal_config.h"
  65 
  66 #include "opal/mca/mca.h"
  67 #include "opal/mca/base/base.h"
  68 
  69 BEGIN_C_DECLS
  70 
  71 /**
  72  * Prototype for doing something once memory changes have been
  73  * detected.  This function is assumed to do whatever is necessary to
  74  * a) figured out what has changed, and b) adjust OMPI as relevant
  75  * (e.g., call opal_mem_hooks_release_hook).  It only needs to be
  76  * supplied for components that provide opal_memory_changed() macros
  77  * that can return non-zero.
  78  */
  79 typedef int (*opal_memory_base_component_process_fn_t)(void);
  80 
  81 /**
  82  * Prototype for a function that is invoked when the memory base is
  83  * trying to select a component. This funtionality is required.
  84  */
  85 typedef int (*opal_memory_base_component_query_fn_t)(int *priority);
  86 
  87 /**
  88  * Prototype for a function that is invoked when Open MPI starts to
  89  * "care" about a specific memory region.  That is, Open MPI declares
  90  * that it wants to be notified if the memory mapping for this region
  91  * changes.
  92  *
  93  * If a component does not want/need to provide this functionality, it
  94  * can use the value opal_memory_base_register_empty (an empty
  95  * implementation of this function).
  96  */
  97 typedef int (*opal_memory_base_component_register_fn_t)(void *base,
  98                                                         size_t len,
  99                                                         uint64_t cookie);
 100 
 101 
 102 /**
 103  * Prototype for a function that is the opposite of
 104  * opal_memory_base_component_register_fn_t: this function is invoked
 105  * when Open MPI stops to "caring" about a specific memory region.
 106  * That is, Open MPI declares that it no longer wants to be notified
 107  * if the memory mapping for this region changes.
 108  *
 109  * The parameters of this function will exactly match parameters that
 110  * were previously passed to the call to
 111  * opal_memory_base_component_register_fn_t.
 112  *
 113  * If a component does not want/need to provide this functionality, it
 114  * can use the value opal_memory_base_deregister_empty (an empty
 115  * implementation of this function).
 116  */
 117 typedef int (*opal_memory_base_component_deregister_fn_t)(void *base,
 118                                                           size_t len,
 119                                                           uint64_t cookie);
 120 
 121 
 122 /**
 123  * Prototype for a function that set the memory alignment
 124  */
 125 typedef void (*opal_memory_base_component_set_alignment_fn_t)(int use_memalign,
 126                                                               size_t memalign_threshold);
 127 
 128 /**
 129  * Function to be called when initializing malloc hooks
 130  */
 131 typedef void (*opal_memory_base_component_init_hook_fn_t)(void);
 132 
 133 /**
 134  * Structure for memory components.
 135  */
 136 typedef struct opal_memory_base_component_2_0_0_t {
 137     /** MCA base component */
 138     mca_base_component_t memoryc_version;
 139     /** MCA base data */
 140     mca_base_component_data_t memoryc_data;
 141 
 142     opal_memory_base_component_query_fn_t memoryc_query;
 143 
 144     /** This function will be called when the malloc hooks are
 145      * initialized. It may be NULL if no hooks are needed. */
 146     opal_memory_base_component_init_hook_fn_t memoryc_init_hook;
 147 
 148     /** Function to call when something has changed, as indicated by
 149         opal_memory_changed().  Will be ignored if the component does
 150         not provide an opal_memory_changed() macro that returns
 151         nonzero.  */
 152     opal_memory_base_component_process_fn_t memoryc_process;
 153 
 154     /** Function invoked when Open MPI starts "caring" about a
 155         specific memory region */
 156     opal_memory_base_component_register_fn_t memoryc_register;
 157     /** Function invoked when Open MPI stops "caring" about a
 158         specific memory region */
 159     opal_memory_base_component_deregister_fn_t memoryc_deregister;
 160     /** Function invoked in order to set malloc'ed memory alignment */
 161     opal_memory_base_component_set_alignment_fn_t memoryc_set_alignment;
 162 } opal_memory_base_component_2_0_0_t;
 163 
 164 OPAL_DECLSPEC extern opal_memory_base_component_2_0_0_t *opal_memory;
 165 
 166 END_C_DECLS
 167 
 168 /*
 169  * Macro for use in components that are of type memory
 170  */
 171 #define OPAL_MEMORY_BASE_VERSION_2_0_0 \
 172     OPAL_MCA_BASE_VERSION_2_1_0("memory", 2, 0, 0)
 173 
 174 #endif /* OPAL_MCA_MEMORY_MEMORY_H */

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