xref: /6.6.0/platform/include/platform/cb_malloc.h (revision becffd3b)
1/* -*- Mode: C++; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
2/*
3 *     Copyright 2016 Couchbase, Inc
4 *
5 *   Licensed under the Apache License, Version 2.0 (the "License");
6 *   you may not use this file except in compliance with the License.
7 *   You may obtain a copy of the License at
8 *
9 *       http://www.apache.org/licenses/LICENSE-2.0
10 *
11 *   Unless required by applicable law or agreed to in writing, software
12 *   distributed under the License is distributed on an "AS IS" BASIS,
13 *   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 *   See the License for the specific language governing permissions and
15 *   limitations under the License.
16 */
17
18/** This file defines the Couchbase memory allocation API.
19 *
20 * It doesn't implement allocation itself - the actual memory allocation will
21 * be performed by an exising 'proper' memory allocator. It exists for
22 * two reasons:
23 *
24 * 1. To give us a single 'interposing' point to use an alternative
25 *    allocator (e.g. jemalloc) instead of the system one.
26 *    (On most *ix platforms it's relatively easy to interpose malloc and
27 *    friends; you can simply define your own symbols in the application binary
28 *    and those will be used; however this isn't possible on Windows so we
29 *    need our own explicit API for the C memory allocation functions).
30 *
31 * 2. To allow us to insert hooks for memory tracking - e.g. so we can track
32 *    how much memory each bucket (aka engine instance) are using.
33 */
34
35#pragma once
36
37#include <platform/dynamic.h>
38#include <platform/visibility.h>
39
40#include <stdlib.h>
41
42#if !defined(__cplusplus)
43#define throwspec
44#else
45#define throwspec throw()
46#endif
47
48/*
49 * Couchbase memory allocation API functions.
50 *
51 * Equivalent to the libc functions with the same suffix.
52 */
53
54#ifdef __cplusplus
55extern "C" {
56#endif
57
58PLATFORM_PUBLIC_API void* cb_malloc(size_t size) throwspec;
59PLATFORM_PUBLIC_API void* cb_calloc(size_t nmemb, size_t size) throwspec;
60PLATFORM_PUBLIC_API void* cb_realloc(void* ptr, size_t size) throwspec;
61PLATFORM_PUBLIC_API void cb_free(void* ptr) throwspec;
62PLATFORM_PUBLIC_API void cb_sized_free(void* ptr, size_t size) throwspec;
63
64#if defined(HAVE_MALLOC_USABLE_SIZE)
65PLATFORM_PUBLIC_API size_t cb_malloc_usable_size(void* ptr) throwspec;
66#endif
67
68#undef throwspec
69
70/*
71 * Replacements for other libc functions which allocate memory via 'malloc'.
72 *
73 * For our 'cb' versions we use cb_malloc instead.
74 */
75
76PLATFORM_PUBLIC_API char* cb_strdup(const char* s1);
77
78#ifdef __cplusplus
79} // extern "C"
80#endif
81
82
83#if defined(__cplusplus)
84/*
85 * Memory allocation / deallocation hook support.
86 *
87 * The following functions allow callbacks (hooks) to be registered, which
88 * are then called on every memory allocation and deallocation.
89 *
90 * Only one hook for each of new & delete can be installed at any time.
91 * Note these are *not* MT-safe - clients should only ever add/remove hooks
92 * from a single thread (or use external locking).
93 */
94
95/**
96 * Callback prototype for new hook. This is called /after/ the memory has
97 * been allocated by the underlying allocator.
98 *
99 * @param ptr Address of memory allocated
100 * @param sz Size in bytes of requested allocation.
101 */
102typedef void(*cb_malloc_new_hook_t)(const void *ptr, size_t sz);
103
104/**
105 * Callback prototype for delete hook. This is called /before/ the memory has
106 * been freed by the underlying allocator.
107 *
108 * @param ptr Address of memory to be deallocated.
109 */
110typedef void(*cb_malloc_delete_hook_t)(const void *ptr);
111
112PLATFORM_PUBLIC_API bool cb_add_new_hook(cb_malloc_new_hook_t f);
113PLATFORM_PUBLIC_API bool cb_remove_new_hook(cb_malloc_new_hook_t f);
114PLATFORM_PUBLIC_API bool cb_add_delete_hook(cb_malloc_delete_hook_t f);
115PLATFORM_PUBLIC_API bool cb_remove_delete_hook(cb_malloc_delete_hook_t f);
116
117/* Functions to call the new / delete hooks; if they are non-null. */
118PLATFORM_PUBLIC_API void cb_invoke_new_hook(const void* ptr, size_t size);
119
120PLATFORM_PUBLIC_API void cb_invoke_delete_hook(const void* ptr);
121
122#endif // __cplusplus
123