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