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
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
/* Copyright © 2023-2024 Apple Inc. */
#ifndef MLX_STREAM_H
#define MLX_STREAM_H
#include <stdbool.h>
#include <stddef.h>
#include "mlx/c/device.h"
#ifdef __cplusplus
extern "C" {
#endif
/**
* \defgroup mlx_stream Stream
* MLX stream object.
*/
/**@{*/
/**
* A MLX stream object.
*/
typedef struct mlx_stream_ {
void* ctx;
} mlx_stream;
/**
* A per-thread stream object.
*
* The same thread-local stream can be used from any number of threads; the
* stream's GPU command encoder is registered once per thread.
*/
typedef struct mlx_stream_thread_local_ {
void* ctx;
} mlx_stream_thread_local;
/**
* A vector of mlx_stream.
* Forward declaration to avoid circular references.
*/
typedef struct mlx_vector_stream_ mlx_vector_stream;
/**
* Returns a new empty stream.
*/
mlx_stream mlx_stream_new(void);
/**
* Returns a new stream on a device.
*/
mlx_stream mlx_stream_new_device(mlx_device dev);
/**
* Returns a new stream on a device that can be used from any thread.
*
* Streams are otherwise thread affine: a stream's GPU command encoder is
* registered per thread, so evaluating on a stream from a thread other than
* the one that created it fails. Streams returned here are registered
* globally instead.
*
* MLX applies no synchronization to these streams -- it is the caller's
* responsibility to ensure there are no data races on them.
*/
mlx_stream mlx_stream_new_thread_unsafe(mlx_device dev);
/**
* Returns a new per-thread stream on a device.
*
* Streams created this way are unique per thread: evaluating the same
* `mlx_stream_thread_local` from different threads yields distinct streams.
*/
mlx_stream_thread_local mlx_stream_thread_local_new(mlx_device dev);
/**
* Set a per-thread stream to the provided src stream.
*/
int mlx_stream_thread_local_set(
mlx_stream_thread_local* tls,
const mlx_stream_thread_local src);
/**
* Free a per-thread stream.
*/
int mlx_stream_thread_local_free(mlx_stream_thread_local tls);
/**
* Returns the concrete stream backing a per-thread stream on the current
* thread.
*/
int mlx_stream_from_thread_local(
mlx_stream* res,
const mlx_stream_thread_local tls);
/**
* Get the vector of available streams.
*/
int mlx_get_streams(mlx_vector_stream* res);
/**
* Set stream to provided src stream.
*/
int mlx_stream_set(mlx_stream* stream, const mlx_stream src);
/**
* Free a stream.
*/
int mlx_stream_free(mlx_stream stream);
/**
* Get stream description.
*/
int mlx_stream_tostring(mlx_string* str, mlx_stream stream);
/**
* Check if streams are the same.
*/
bool mlx_stream_equal(mlx_stream lhs, mlx_stream rhs);
/**
* Return the device of the stream.
*/
int mlx_stream_get_device(mlx_device* dev, mlx_stream stream);
/**
* Return the index of the stream.
*/
int mlx_stream_get_index(int* index, mlx_stream stream);
/**
* Synchronize with the provided stream.
*/
int mlx_synchronize(mlx_stream stream);
/**
* Synchronize with the default stream.
*/
int mlx_synchronize_default(void);
/**
* Synchronize with the stream corresponding to the current thread.
*/
int mlx_synchronize_thread_local(mlx_stream_thread_local tls);
/**
* Destroy all streams created in the current thread.
*/
int mlx_clear_streams(void);
/**
* Returns the default stream on the given device.
*/
int mlx_get_default_stream(mlx_stream* stream, mlx_device dev);
/**
* Set default stream.
*/
int mlx_set_default_stream(mlx_stream stream);
/**
* Returns the current default CPU stream.
*/
mlx_stream mlx_default_cpu_stream_new(void);
/**
* Returns the current default GPU stream.
*/
mlx_stream mlx_default_gpu_stream_new(void);
/**@}*/
#ifdef __cplusplus
}
#endif
#endif