ucx1-sys 0.1.0

Rust FFI bindings to UCX.
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
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

/*
 * Copyright (C) Mellanox Technologies Ltd. 2018.  ALL RIGHTS RESERVED.
 * See file LICENSE for terms.
 */

#ifndef UCS_STRIDED_ALLOC_H_
#define UCS_STRIDED_ALLOC_H_

#include "queue_types.h"

#include <ucs/type/status.h>
#include <ucs/sys/compiler_def.h>
#include <ucs/sys/math.h>
#include <stddef.h>


BEGIN_C_DECLS

/** @file strided_alloc.h */

/* the distance between allocated elements */
#define UCS_STRIDED_ALLOC_STRIDE (128 * UCS_KBYTE)


/**
 * Get a pointer to another element in the strided object
 *
 * Example with stride_count=3:
 *
 * chunk
 * start -+
 *        |
 *        |
 *        | <--    128 kB    --> . <--    128 kB    --> .
 *        |                      .                      .
 *        \/                     .                      .
 *        +--------+--   ...   --+--------+--   ...   --+--------+
 *        | stride |             | stride |             | stride |
 * obj0:  | elem 0 |             | elem 1 |             | elem 2 |
 *        | (base) |             |        |             |        |
 *        +--------+--   ...   --+--------+--   ...   --+--------+
 *                 +--------+--  ...    --+--------+--  ...    --+--------+
 *                 | stride |             | stride |             | stride |
 * obj1:           | elem 0 |             | elem 1 |             | elem 2 |
 *                 | (base) |             |        |             |        |
 *                 +--------+--  ...     -+--------+--  ...    --+--------+
 *                          +--------+--  ...    --+--------+--   ...   --+--------+
 *                          | stride |             | stride |             | stride |
 * obj2:                    | elem 0 |             | elem 1 |             | elem 2 |
 *                          | (base) |             |        |             |        |
 *                          +--------+--  ...     -+--------+--   ...   --+--------+
 *
 * ...
 *
 * @param _elem        Pointer to the current element
 * @param _stride_idx  Stride index of the current element
 * @param _wanted_idx  Stride index of the desired element
 *
 * @return Pointer to the desired element
 */
#define ucs_strided_elem_get(_elem, _stride_idx, _wanted_idx) \
    UCS_PTR_BYTE_OFFSET(_elem, (ptrdiff_t)UCS_STRIDED_ALLOC_STRIDE * \
                        ((ptrdiff_t)(_wanted_idx) - (ptrdiff_t)(_stride_idx)))


/* Forward declaration, used internally */
typedef struct ucs_strided_alloc_elem ucs_strided_alloc_elem_t;


/**
 * Strided allocator - allows allocating objects which are split to several
 * memory areas with a constant stride (gap) in-between.
 * This improves the cache locality when the first memory area is used mostly.
 */
typedef struct ucs_strided_alloc {
    ucs_strided_alloc_elem_t  *freelist;    /* LIFO of free elements */
    ucs_queue_head_t          chunks;       /* Queue of allocated chunks */
    size_t                    elem_size;    /* Size of a single memory area */
    unsigned                  stride_count; /* Number of strides */
    unsigned                  inuse_count;  /* Number of allocated elements */
} ucs_strided_alloc_t;


/**
 * Initialize the split allocator context
 *
 * @param [in] sa            Strided allocator structure to initialize
 * @param [in] elem_size     Size of a single stride element
 * @param [in] stride_count  How many memory strides per object
 */
void ucs_strided_alloc_init(ucs_strided_alloc_t *sa, size_t elem_size,
                            unsigned stride_count);


/**
 * Cleanup the split allocator context
 *
 * @param [in] sa           Strided allocator structure to cleanup
 */
void ucs_strided_alloc_cleanup(ucs_strided_alloc_t *sa);


/**
 * Allocate an object
 *
 * @param [in] sa            Strided allocator to allocate on
 * @param [in] alloc_name    Debug name of the allocation
 *
 * @return Pointer to the first stride of the allocated object.
 */
void* ucs_strided_alloc_get(ucs_strided_alloc_t *sa, const char *alloc_name);


/**
 * Release an object
 *
 * @param [in] sa            Strided allocator to release the object to
 * @param [in] base          Pointer to the first stride of the object to release
 */
void ucs_strided_alloc_put(ucs_strided_alloc_t *sa, void *base);


/**
 * Get the number of currently allocated objects
 *
 * @param [in] sa            Strided allocator to get the information for
*
 * @return Number of currently allocated objects
 */
unsigned ucs_strided_alloc_inuse_count(ucs_strided_alloc_t *sa);


END_C_DECLS

#endif