src/cx/streams.h

Thu, 16 Oct 2025 19:57:47 +0200

author
Mike Becker <universe@uap-core.de>
date
Thu, 16 Oct 2025 19:57:47 +0200
changeset 1426
3a89b31f0724
parent 1424
563033aa998c
permissions
-rw-r--r--

clean up header files and adds support for comparing arbitrary strings with string.h functions

483
929016224c3c add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
1 /*
929016224c3c add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
929016224c3c add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
3 *
929016224c3c add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
4 * Copyright 2021 Mike Becker, Olaf Wintermann All rights reserved.
929016224c3c add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
5 *
929016224c3c add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
6 * Redistribution and use in source and binary forms, with or without
929016224c3c add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
7 * modification, are permitted provided that the following conditions are met:
929016224c3c add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
8 *
929016224c3c add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
9 * 1. Redistributions of source code must retain the above copyright
929016224c3c add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
10 * notice, this list of conditions and the following disclaimer.
929016224c3c add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
11 *
929016224c3c add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
12 * 2. Redistributions in binary form must reproduce the above copyright
929016224c3c add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
13 * notice, this list of conditions and the following disclaimer in the
929016224c3c add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
14 * documentation and/or other materials provided with the distribution.
929016224c3c add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
15 *
929016224c3c add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
929016224c3c add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
17 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
929016224c3c add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
18 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
929016224c3c add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
19 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
929016224c3c add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
20 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
929016224c3c add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
21 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
929016224c3c add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
22 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
929016224c3c add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
23 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
929016224c3c add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
24 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
929016224c3c add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
25 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
929016224c3c add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
26 * POSSIBILITY OF SUCH DAMAGE.
929016224c3c add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
27 */
929016224c3c add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
28
929016224c3c add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
29 /**
1099
ce5eb95ffba2 refine docs for streams.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
30 * @file streams.h
483
929016224c3c add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
31 *
1099
ce5eb95ffba2 refine docs for streams.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
32 * @brief Utility functions for data streams.
483
929016224c3c add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
33 *
1099
ce5eb95ffba2 refine docs for streams.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
34 * @author Mike Becker
ce5eb95ffba2 refine docs for streams.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
35 * @author Olaf Wintermann
ce5eb95ffba2 refine docs for streams.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
36 * @copyright 2-Clause BSD License
483
929016224c3c add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
37 */
929016224c3c add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
38
971
cc204fc56c9c rename utils.h to streams.h
Mike Becker <universe@uap-core.de>
parents: 970
diff changeset
39 #ifndef UCX_STREAMS_H
cc204fc56c9c rename utils.h to streams.h
Mike Becker <universe@uap-core.de>
parents: 970
diff changeset
40 #define UCX_STREAMS_H
483
929016224c3c add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
41
929016224c3c add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
42 #include "common.h"
929016224c3c add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
43
929016224c3c add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
44 #ifdef __cplusplus
929016224c3c add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
45 extern "C" {
929016224c3c add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
46 #endif
929016224c3c add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
47
674
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
48 /**
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
49 * Reads data from a stream and writes it to another stream.
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
50 *
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
51 * @param src the source stream
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
52 * @param dest the destination stream
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
53 * @param rfnc the read function
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
54 * @param wfnc the write function
1099
ce5eb95ffba2 refine docs for streams.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
55 * @param buf a pointer to the copy buffer or @c NULL if a buffer
674
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
56 * shall be implicitly created on the heap
1424
563033aa998c fixes tons of typos and grammar issues across the documentation - fixes #667
Mike Becker <universe@uap-core.de>
parents: 1180
diff changeset
57 * @param bufsize the size of the copy buffer - if @p buf is @c NULL, you can
674
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
58 * set this to zero to let the implementation decide
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
59 * @param n the maximum number of bytes that shall be copied.
1099
ce5eb95ffba2 refine docs for streams.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
60 * If this is larger than @p bufsize, the content is copied over multiple
674
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
61 * iterations.
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
62 * @return the total number of bytes copied
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
63 */
985
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 971
diff changeset
64 cx_attr_nonnull_arg(1, 2, 3, 4)
1426
3a89b31f0724 clean up header files and adds support for comparing arbitrary strings with string.h functions
Mike Becker <universe@uap-core.de>
parents: 1424
diff changeset
65 cx_attr_access_r(1) cx_attr_access_w(2) cx_attr_access_w(5)
3a89b31f0724 clean up header files and adds support for comparing arbitrary strings with string.h functions
Mike Becker <universe@uap-core.de>
parents: 1424
diff changeset
66 CX_EXPORT size_t cx_stream_bncopy(void *src, void *dest,
3a89b31f0724 clean up header files and adds support for comparing arbitrary strings with string.h functions
Mike Becker <universe@uap-core.de>
parents: 1424
diff changeset
67 cx_read_func rfnc, cx_write_func wfnc,
3a89b31f0724 clean up header files and adds support for comparing arbitrary strings with string.h functions
Mike Becker <universe@uap-core.de>
parents: 1424
diff changeset
68 char *buf, size_t bufsize, size_t n);
674
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
69
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
70 /**
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
71 * Reads data from a stream and writes it to another stream.
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
72 *
1099
ce5eb95ffba2 refine docs for streams.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
73 * @param src (@c void*) the source stream
ce5eb95ffba2 refine docs for streams.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
74 * @param dest (@c void*) the destination stream
ce5eb95ffba2 refine docs for streams.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
75 * @param rfnc (@c cx_read_func) the read function
ce5eb95ffba2 refine docs for streams.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
76 * @param wfnc (@c cx_write_func) the write function
ce5eb95ffba2 refine docs for streams.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
77 * @param buf (@c char*) a pointer to the copy buffer or @c NULL if a buffer
674
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
78 * shall be implicitly created on the heap
1099
ce5eb95ffba2 refine docs for streams.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
79 * @param bufsize (@c size_t) the size of the copy buffer - if @p buf is
1424
563033aa998c fixes tons of typos and grammar issues across the documentation - fixes #667
Mike Becker <universe@uap-core.de>
parents: 1180
diff changeset
80 * @c NULL, you can set this to zero to let the implementation decide
674
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
81 * @return total number of bytes copied
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
82 */
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
83 #define cx_stream_bcopy(src, dest, rfnc, wfnc, buf, bufsize) \
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
84 cx_stream_bncopy(src, dest, rfnc, wfnc, buf, bufsize, SIZE_MAX)
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
85
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
86 /**
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
87 * Reads data from a stream and writes it to another stream.
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
88 *
1424
563033aa998c fixes tons of typos and grammar issues across the documentation - fixes #667
Mike Becker <universe@uap-core.de>
parents: 1180
diff changeset
89 * The data is temporarily stored in a stack-allocated buffer.
674
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
90 *
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
91 * @param src the source stream
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
92 * @param dest the destination stream
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
93 * @param rfnc the read function
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
94 * @param wfnc the write function
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
95 * @param n the maximum number of bytes that shall be copied.
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
96 * @return total number of bytes copied
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
97 */
1426
3a89b31f0724 clean up header files and adds support for comparing arbitrary strings with string.h functions
Mike Becker <universe@uap-core.de>
parents: 1424
diff changeset
98 cx_attr_nonnull cx_attr_access_r(1) cx_attr_access_w(2)
3a89b31f0724 clean up header files and adds support for comparing arbitrary strings with string.h functions
Mike Becker <universe@uap-core.de>
parents: 1424
diff changeset
99 CX_EXPORT size_t cx_stream_ncopy(void *src, void *dest,
3a89b31f0724 clean up header files and adds support for comparing arbitrary strings with string.h functions
Mike Becker <universe@uap-core.de>
parents: 1424
diff changeset
100 cx_read_func rfnc, cx_write_func wfnc, size_t n);
674
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
101
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
102 /**
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
103 * Reads data from a stream and writes it to another stream.
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
104 *
1424
563033aa998c fixes tons of typos and grammar issues across the documentation - fixes #667
Mike Becker <universe@uap-core.de>
parents: 1180
diff changeset
105 * The data is temporarily stored in a stack-allocated buffer.
674
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
106 *
1099
ce5eb95ffba2 refine docs for streams.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
107 * @param src (@c void*) the source stream
ce5eb95ffba2 refine docs for streams.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
108 * @param dest (@c void*) the destination stream
ce5eb95ffba2 refine docs for streams.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
109 * @param rfnc (@c cx_read_func) the read function
ce5eb95ffba2 refine docs for streams.h - issue #548
Mike Becker <universe@uap-core.de>
parents: 985
diff changeset
110 * @param wfnc (@c cx_write_func) the write function
674
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
111 * @return total number of bytes copied
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
112 */
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
113 #define cx_stream_copy(src, dest, rfnc, wfnc) \
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
114 cx_stream_ncopy(src, dest, rfnc, wfnc, SIZE_MAX)
483
929016224c3c add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
115
929016224c3c add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
116 #ifdef __cplusplus
929016224c3c add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
117 }
929016224c3c add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
118 #endif
929016224c3c add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
119
971
cc204fc56c9c rename utils.h to streams.h
Mike Becker <universe@uap-core.de>
parents: 970
diff changeset
120 #endif // UCX_STREAMS_H

mercurial