Zen API

- Home
- Help Topics
- Types by Category
- All Types
- Files

All Classes Files Functions Variables Typedefs Macros Groups Pages
kApiLib.h
Go to the documentation of this file.
1 /**
2 * @file kApiLib.h
3 * @brief Zen API library management functions.
4 *
5 * @internal
6 * Copyright (C) 2012-2014 by LMI Technologies Inc.
7 * Licensed under the MIT License.
8 * Redistributed files must retain the above copyright notice.
9 */
10 #include <kApi/kApiDef.h> //--inclusion order controlled by kApiDef
11
12 #ifndef K_API_API_LIB_H
13 #define K_API_API_LIB_H
14
15 kBeginHeader()
16
17 /** Function signature for memory allocation handler. */
18 typedef kStatus (kCall* kApiMemAllocFx)(kPointer provider, kSize size, void* mem);
19
20 /** Function signature for memory free handler. */
21 typedef kStatus (kCall* kApiMemFreeFx)(kPointer provider, void* mem);
22
23 /**
24 * Constructs the Zen API type assembly (kApiLib).
25 *
26 * This function initializes the Zen API assembly and returns a handle that represents the assembly.
27 * When the assembly is no longer needed, pass the assembly handle to the kObject_Destroy function.
28 *
29 * This function should be called prior to calling most other Zen API functions. The only exceptions to
30 * this rule are kApiLib functions that configure global handlers (e.g. kApiLib_SetMemAllocHandlers); these functions
31 * should typically be called prior to kApiLib_Construct.
32 *
33 * Multiple nested calls to this function will return the same assembly instance. To ensure final clean up, the
34 * kObject_Destroy function should be invoked a corresponding number of times on the assembly handle.
35 *
36 * @param assembly Receives a handle to the kApiLib type assembly.
37 * @return Operation status.
38 */
39 kFx(kStatus) kApiLib_Construct(kAssembly* assembly);
40
41 /**
42 * Sets handler functions for memory alloc/free operations.
43 *
44 * By default, kApiLib uses C standard library functions for memory allocation. Call this function
45 * to override the default behaviour.
46 *
47 * This function is not thread-safe and should be called before calling kApiLib_Construct.
48 *
49 * @param allocFx Memory allocation callback function.
50 * @param freeFx Memory deallocation callback function.
51 * @param provider Context pointer (provided to callback functions).
52 * @return Operation status.
53 */
54 kFx(kStatus) kApiLib_SetMemAllocHandlers(kApiMemAllocFx allocFx, kApiMemFreeFx freeFx, kPointer provider);
55
56 kEndHeader()
57
58 #include <kApi/kApiLib.x.h>
59
60 #endif
kApiLib_SetMemAllocHandlers
kStatus kApiLib_SetMemAllocHandlers(kApiMemAllocFx allocFx, kApiMemFreeFx freeFx, kPointer provider)
Sets handler functions for memory alloc/free operations.
kAssembly
Represents a library of types.
kPointer
Represents a void pointer.
kSize
Represents an unsigned integer that can store a pointer address.
kApiMemAllocFx
kStatus(kCall * kApiMemAllocFx)(kPointer provider, kSize size, void *mem)
Function signature for memory allocation handler.
Definition: kApiLib.h:18
kApiMemFreeFx
kStatus(kCall * kApiMemFreeFx)(kPointer provider, void *mem)
Function signature for memory free handler.
Definition: kApiLib.h:21
kApiDef.h
Essential API declarations.
kApiLib_Construct
kStatus kApiLib_Construct(kAssembly *assembly)
Constructs the Zen API type assembly (kApiLib).
kStatus
Represents an enumeration of error codes.
kCall
#define kCall
kApi standard function calling convention.
Definition: kApiDef.h:17