rust_macios/core_foundation/
cf_allocator.rs

1use std::fmt;
2
3use libc::c_void;
4
5use crate::declare_CFType;
6
7use super::{CFIndex, CFOptionFlags, CFStringRef, CFType, CFTypeObject, CFTypeRef};
8
9#[repr(C)]
10pub struct __CFAllocator(c_void);
11
12/// A reference to a [`CFAllocator`] object.
13pub type CFAllocatorRef = *const __CFAllocator;
14
15declare_CFType! {
16    /// CFAllocator is an opaque type that allocates and deallocates memory for you.
17    CFAllocator, CFAllocatorRef
18}
19
20/// A prototype for a function callback that retains the given data.
21pub type CFAllocatorRetainCallBack = extern "C" fn(info: *mut c_void) -> *mut c_void;
22/// A prototype for a function callback that releases the given data.
23pub type CFAllocatorReleaseCallBack = extern "C" fn(info: *mut c_void);
24/// A prototype for a function callback that provides a description of the specified data.
25pub type CFAllocatorCopyDescriptionCallBack = extern "C" fn(info: *mut c_void) -> CFStringRef;
26/// A prototype for a function callback that allocates memory of a requested size.
27pub type CFAllocatorAllocateCallBack =
28    extern "C" fn(allocSize: CFIndex, hint: CFOptionFlags, info: *mut c_void) -> *mut c_void;
29/// A prototype for a function callback that reallocates memory of a requested size for an existing block of memory.
30pub type CFAllocatorReallocateCallBack = extern "C" fn(
31    ptr: *mut c_void,
32    newsize: CFIndex,
33    hint: CFOptionFlags,
34    info: *mut c_void,
35) -> *mut c_void;
36/// A prototype for a function callback that deallocates a block of memory.
37pub type CFAllocatorDeallocateCallBack = extern "C" fn(ptr: *mut c_void, info: *mut c_void);
38/// A prototype for a function callback that gives the size of memory likely to be allocated, given a certain request.
39pub type CFAllocatorPreferredSizeCallBack =
40    extern "C" fn(size: CFIndex, hint: CFOptionFlags, info: *mut c_void) -> CFIndex;
41
42/// A structure that defines the context or operating environment for an allocator (CFAllocator) object. Every Core Foundation allocator object must have a context defined for it.
43#[repr(C)]
44#[derive(Debug, Clone, Copy)]
45pub struct CFAllocatorContext {
46    /// An integer of type CFIndex. Assign the version number of the allocator. Currently the only valid value is 0.
47    pub version: CFIndex,
48    /// An untyped pointer to program-defined data. Allocate memory for this data and assign a pointer to it. This data is often control information for the allocator. You may assign NULL.
49    pub info: *mut c_void,
50    /// A prototype for a function callback that retains the data pointed to by the info field. In implementing this function, retain the data you have defined for the allocator context in this field. (This might make sense only if the data is a Core Foundation object.) You may set this function pointer to NULL.
51    pub retain: Option<CFAllocatorRetainCallBack>,
52    /// A prototype for a function callback that releases the data pointed to by the info field. In implementing this function, release (or free) the data you have defined for the allocator context. You may set this function pointer to NULL, but doing so might result in memory leaks.
53    pub release: Option<CFAllocatorReleaseCallBack>,
54    /// A prototype for a function callback that provides a description of the data pointed to by the info field. In implementing this function, return a reference to a CFString object that describes your allocator, particularly some characteristics of your program-defined data. You may set this function pointer to NULL, in which case Core Foundation will provide a rudimentary description.
55    pub copy_description: Option<CFAllocatorCopyDescriptionCallBack>,
56    /// A prototype for a function callback that allocates memory of a requested size. In implementing this function, allocate a block of memory of at least size bytes and return a pointer to the start of the block. The hint argument is a bitfield that you should currently not use (that is, assign 0). The size parameter should always be greater than 0. If it is not, or if problems in allocation occur, return NULL. This function pointer may not be assigned NULL.
57    pub allocate: Option<CFAllocatorAllocateCallBack>,
58    /// A prototype for a function callback that reallocates memory of a requested size for an existing block of memory.
59    pub reallocate: Option<CFAllocatorReallocateCallBack>,
60    /// A prototype for a function callback that deallocates a given block of memory. In implementing this function, make the block of memory pointed to by ptr available for subsequent reuse by the allocator but unavailable for continued use by the program. The ptr parameter cannot be NULL and if the ptr parameter is not a block of memory that has been previously allocated by the allocator, the results are undefined; abnormal program termination can occur. You can set this callback to NULL, in which case the CFAllocatorDeallocate function has no effect.
61    pub deallocate: Option<CFAllocatorDeallocateCallBack>,
62    /// A prototype for a function callback that determines whether there is enough free memory to satisfy a request. In implementing this function, return the actual size the allocator is likely to allocate given a request for a block of memory of size size. The hint argument is a bitfield that you should currently not use.
63    pub preferred_size: Option<CFAllocatorPreferredSizeCallBack>,
64}
65
66impl fmt::Debug for CFAllocator {
67    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
68        unsafe {
69            write!(
70                f,
71                "{:?}",
72                CFType::copy_description(self.get_internal_object() as CFTypeRef)
73            )
74        }
75    }
76}
77
78extern "C" {
79    /* Predefined Allocators
80     */
81
82    /// This is a synonym for NULL.
83    pub static kCFAllocatorDefault: CFAllocatorRef;
84    /// Default system allocator.
85    pub static kCFAllocatorSystemDefault: CFAllocatorRef;
86    /// This allocator uses malloc(), realloc(), and free().
87    pub static kCFAllocatorMalloc: CFAllocatorRef;
88    /// This allocator explicitly uses the default malloc zone, returned by malloc_default_zone().
89    pub static kCFAllocatorMallocZone: CFAllocatorRef;
90    /// This allocator does nothing—it allocates no memory.
91    pub static kCFAllocatorNull: CFAllocatorRef;
92    /// Special allocator argument to CFAllocatorCreate—it uses the functions given in the context to allocate the allocator.
93    pub static kCFAllocatorUseContext: CFAllocatorRef;
94}
rust_macios/core_foundation/cf_allocator.rs

rust_macios/core_foundation/
cf_allocator.rs
