cpython/Include/pymem.h at pythoncapi · pythoncapi/cpython · GitHub

History

244 lines (190 loc) · 8.77 KB

Raw

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

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

235

236

237

238

239

240

241

242

243

244

/* The PyMem_ family: low-level memory allocation interfaces.

See objimpl.h for the PyObject_ memory family.

#ifndef Py_PYMEM_H

#define Py_PYMEM_H

#include "pyport.h"

#ifdef __cplusplus

extern "C" {

#endif

#ifndef Py_LIMITED_API

PyAPI_FUNC(void *) PyMem_RawMalloc(size_t size);

PyAPI_FUNC(void *) PyMem_RawCalloc(size_t nelem, size_t elsize);

PyAPI_FUNC(void *) PyMem_RawRealloc(void *ptr, size_t new_size);

PyAPI_FUNC(void) PyMem_RawFree(void *ptr);

/* Configure the Python memory allocators. Pass NULL to use default

allocators. */

PyAPI_FUNC(int) _PyMem_SetupAllocators(const char *opt);

/* Try to get the allocators name set by _PyMem_SetupAllocators(). */

PyAPI_FUNC(const char*) _PyMem_GetAllocatorsName(void);

/* Track an allocated memory block in the tracemalloc module.

Return 0 on success, return -1 on error (failed to allocate memory to store

the trace).

Return -2 if tracemalloc is disabled.

If memory block is already tracked, update the existing trace. */

PyAPI_FUNC(int) PyTraceMalloc_Track(

unsigned int domain,

uintptr_t ptr,

size_t size);

/* Untrack an allocated memory block in the tracemalloc module.

Do nothing if the block was not tracked.

Return -2 if tracemalloc is disabled, otherwise return 0. */

PyAPI_FUNC(int) PyTraceMalloc_Untrack(

unsigned int domain,

uintptr_t ptr);

/* Get the traceback where a memory block was allocated.

Return a tuple of (filename: str, lineno: int) tuples.

Return None if the tracemalloc module is disabled or if the memory block

is not tracked by tracemalloc.

Raise an exception and return NULL on error. */

PyAPI_FUNC(PyObject*) _PyTraceMalloc_GetTraceback(

unsigned int domain,

uintptr_t ptr);

#endif /* !Py_LIMITED_API */

/* BEWARE:

Each interface exports both functions and macros. Extension modules should

use the functions, to ensure binary compatibility across Python versions.

Because the Python implementation is free to change internal details, and

the macros may (or may not) expose details for speed, if you do use the

macros you must recompile your extensions with each Python release.

Never mix calls to PyMem_ with calls to the platform malloc/realloc/

calloc/free. For example, on Windows different DLLs may end up using

different heaps, and if you use PyMem_Malloc you'll get the memory from the

heap used by the Python DLL; it could be a disaster if you free()'ed that

directly in your own extension. Using PyMem_Free instead ensures Python

can return the memory to the proper heap. As another example, in

PYMALLOC_DEBUG mode, Python wraps all calls to all PyMem_ and PyObject_

memory functions in special debugging wrappers that add additional

debugging info to dynamic memory blocks. The system routines have no idea

what to do with that stuff, and the Python wrappers have no idea what to do

with raw blocks obtained directly by the system routines then.

The GIL must be held when using these APIs.

* Raw memory interface

* ====================

/* Functions

Functions supplying platform-independent semantics for malloc/realloc/

free. These functions make sure that allocating 0 bytes returns a distinct

non-NULL pointer (whenever possible -- if we're flat out of memory, NULL

may be returned), even if the platform malloc and realloc don't.

Returned pointers must be checked for NULL explicitly. No action is

performed on failure (no exception is set, no warning is printed, etc).

PyAPI_FUNC(void *) PyMem_Malloc(size_t size);

#if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03050000

PyAPI_FUNC(void *) PyMem_Calloc(size_t nelem, size_t elsize);

#endif

PyAPI_FUNC(void *) PyMem_Realloc(void *ptr, size_t new_size);

PyAPI_FUNC(void) PyMem_Free(void *ptr);

#ifndef Py_LIMITED_API

/* strdup() using PyMem_RawMalloc() */

PyAPI_FUNC(char *) _PyMem_RawStrdup(const char *str);

/* strdup() using PyMem_Malloc() */

PyAPI_FUNC(char *) _PyMem_Strdup(const char *str);

/* wcsdup() using PyMem_RawMalloc() */

PyAPI_FUNC(wchar_t*) _PyMem_RawWcsdup(const wchar_t *str);

#endif

/* Macros. */

/* PyMem_MALLOC(0) means malloc(1). Some systems would return NULL

for malloc(0), which would be treated as an error. Some platforms

would return a pointer with no memory behind it, which would break

pymalloc. To solve these problems, allocate an extra byte. */

/* Returns NULL to indicate error if a negative size or size larger than

Py_ssize_t can represent is supplied. Helps prevents security holes. */

#define PyMem_MALLOC(n) PyMem_Malloc(n)

#define PyMem_REALLOC(p, n) PyMem_Realloc(p, n)

#define PyMem_FREE(p) PyMem_Free(p)

* Type-oriented memory interface

* ==============================

* Allocate memory for n objects of the given type. Returns a new pointer

* or NULL if the request was too large or memory allocation failed. Use

* these macros rather than doing the multiplication yourself so that proper

* overflow checking is always done.

#define PyMem_New(type, n) \

( ((size_t)(n) > PY_SSIZE_T_MAX / sizeof(type)) ? NULL : \

( (type *) PyMem_Malloc((n) * sizeof(type)) ) )

#define PyMem_NEW(type, n) \

( ((size_t)(n) > PY_SSIZE_T_MAX / sizeof(type)) ? NULL : \

( (type *) PyMem_MALLOC((n) * sizeof(type)) ) )

* The value of (p) is always clobbered by this macro regardless of success.

* The caller MUST check if (p) is NULL afterwards and deal with the memory

* error if so. This means the original value of (p) MUST be saved for the

* caller's memory error handler to not lose track of it.

#define PyMem_Resize(p, type, n) \

( (p) = ((size_t)(n) > PY_SSIZE_T_MAX / sizeof(type)) ? NULL : \

(type *) PyMem_Realloc((p), (n) * sizeof(type)) )

#define PyMem_RESIZE(p, type, n) \

( (p) = ((size_t)(n) > PY_SSIZE_T_MAX / sizeof(type)) ? NULL : \

(type *) PyMem_REALLOC((p), (n) * sizeof(type)) )

/* PyMem{Del,DEL} are left over from ancient days, and shouldn't be used

* anymore. They're just confusing aliases for PyMem_{Free,FREE} now.

#define PyMem_Del PyMem_Free

#define PyMem_DEL PyMem_FREE

#ifndef Py_LIMITED_API

typedef enum {

/* PyMem_RawMalloc(), PyMem_RawRealloc() and PyMem_RawFree() */

PYMEM_DOMAIN_RAW,

/* PyMem_Malloc(), PyMem_Realloc() and PyMem_Free() */

PYMEM_DOMAIN_MEM,

/* PyObject_Malloc(), PyObject_Realloc() and PyObject_Free() */

PYMEM_DOMAIN_OBJ

} PyMemAllocatorDomain;

typedef struct {

/* user context passed as the first argument to the 4 functions */

void *ctx;

/* allocate a memory block */

void* (*malloc) (void *ctx, size_t size);

/* allocate a memory block initialized by zeros */

void* (*calloc) (void *ctx, size_t nelem, size_t elsize);

/* allocate or resize a memory block */

void* (*realloc) (void *ctx, void *ptr, size_t new_size);

/* release a memory block */

void (*free) (void *ctx, void *ptr);

} PyMemAllocatorEx;

/* Get the memory block allocator of the specified domain. */

PyAPI_FUNC(void) PyMem_GetAllocator(PyMemAllocatorDomain domain,

PyMemAllocatorEx *allocator);

/* Set the memory block allocator of the specified domain.

The new allocator must return a distinct non-NULL pointer when requesting

zero bytes.

For the PYMEM_DOMAIN_RAW domain, the allocator must be thread-safe: the GIL

is not held when the allocator is called.

If the new allocator is not a hook (don't call the previous allocator), the

PyMem_SetupDebugHooks() function must be called to reinstall the debug hooks

on top on the new allocator. */

PyAPI_FUNC(void) PyMem_SetAllocator(PyMemAllocatorDomain domain,

PyMemAllocatorEx *allocator);

/* Setup hooks to detect bugs in the following Python memory allocator

functions:

- PyMem_RawMalloc(), PyMem_RawRealloc(), PyMem_RawFree()

- PyMem_Malloc(), PyMem_Realloc(), PyMem_Free()

- PyObject_Malloc(), PyObject_Realloc() and PyObject_Free()

Newly allocated memory is filled with the byte 0xCB, freed memory is filled

with the byte 0xDB. Additional checks:

- detect API violations, ex: PyObject_Free() called on a buffer allocated

by PyMem_Malloc()

- detect write before the start of the buffer (buffer underflow)

- detect write after the end of the buffer (buffer overflow)

The function does nothing if Python is not compiled is debug mode. */

PyAPI_FUNC(void) PyMem_SetupDebugHooks(void);

#endif

#ifdef Py_BUILD_CORE

/* Set the memory allocator of the specified domain to the default.

Save the old allocator into *old_alloc if it's non-NULL.

Return on success, or return -1 if the domain is unknown. */

PyAPI_FUNC(int) _PyMem_SetDefaultAllocator(

PyMemAllocatorDomain domain,

PyMemAllocatorEx *old_alloc);

#endif

#ifdef __cplusplus

}

#endif

#endif /* !Py_PYMEM_H */

cpython/Include/pymem.h at pythoncapi · pythoncapi/cpython · GitHub

Uh oh!

Expand file tree

Breadcrumbs

pymem.h

Latest commit

History

Breadcrumbs

pymem.h

File metadata and controls