1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
|
/* -*- Mode: C; c-basic-offset:4 ; indent-tabs-mode:nil -*- */
/*
* 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 (c) 2018 Triad National Security, LLC. 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 "opal_config.h"
#include "memory_internal.h"
BEGIN_C_DECLS
/**
* 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);
/**
* 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 subsystem can trigger
* callback events when memory is going
* to be released by the process, either
* by the user calling an allocator
* function or munmap. Implies
* OPAL_MEMORY_MUNMAP_SUPPORT.
* @retval OPAL_MEMORY_MUNMAP_SUPPORT Subsystem can trigger callback events
* by the user calling munmap directly.
* @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 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 length 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 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 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);
END_C_DECLS
#endif /* OPAL_MEMORY_MEMORY_H */
|
