OpenMPI 0.1.1

- Main Page
- Related Pages
- Modules
- Data Structures
- Files

- File List
- Globals

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 */