slitter 0.1.0

A C- and Rust-callable slab allocator with a focus on safety
Documentation 
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

#pragma once

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>

/**
 * Each slitter object class is uniquely identified by a non-zero
 * 32-bit integer.
 *
 * Passing a zero-initialised `slitter_class` to `slitter_allocate`
 * or `slitter_release` causes undefined behaviour.
 */
struct slitter_class {
	uint32_t id;
};

struct slitter_class_config {
	/*
	 * The name of the object class. Nullable. 
	 *
	 * Must point to a NUL-terminated string of utf-8 bytes if non-NULL.
	 */
	const char *name;

	/*
	 * The size of each object in the allocation class.  Allocations
	 * are only guaranteed alignment to 8 bytes.
	 */
	size_t size;

	/*
	 * If true, zero-fill recycled allocations.
	 */
	bool zero_init;

        /*
         * The name of the underlying mapper, or NULL for default.
         *
         * A mapper name of "file" will use the file-backed mapper.
         */
        const char *mapper_name;
};

#define DEFINE_SLITTER_CLASS(NAME, ...)					\
	struct slitter_class NAME;					\
									\
	__attribute__((__constructor__))				\
	static void slitter_register_##NAME##_fn(void)			\
	{								\
									\
		NAME = slitter_class_register(				\
		    &(struct slitter_class_config) { __VA_ARGS__ });	\
		return;							\
	}


/**
 * Registers a new allocation class, or dies trying.
 *
 * The config must be a valid pointer.  On error, this function will abort.
 */
struct slitter_class slitter_class_register(const struct slitter_class_config *);

/**
 * Updates the parent directory for the file-backed slabs' backing
 * files.  NULL resets to the default.
 *
 * The default directory is `TMPFILE`, or `/tmp/`, and will be used if
 * this function is not called before the first file-backed slab
 * allocation.
 *
 * It is safe to call this function at any time.  However, the update
 * will only take effect when Slitter maps a new 1 GB chunk of data.
 */
void slitter_set_file_backed_slab_directory(const char *directory);

/**
 * Returns a new allocation for the object class.
 *
 * On error, this function will abort.
 *
 * Behaviour is undefined if the `slitter_class` argument is
 * zero-filled or was otherwise not returned by
 * `slitter_class_register`.
 */
void *slitter_allocate(struct slitter_class);

/**
 * Passes ownership of `ptr` back to the object class.
 *
 * `ptr` must be NULL, or have been returned by a call to
 * `slitter_alloc`.
 *
 * On error, this function will abort.
 *
 * Behaviour is undefined if the `slitter_class` argument is
 * zero-filled or was otherwise not returned by
 * `slitter_class_register`.
 */
void slitter_release(struct slitter_class, void *ptr);