src/cx/streams.h

Sun, 22 Dec 2024 21:33:10 +0100

author
Mike Becker <universe@uap-core.de>
date
Sun, 22 Dec 2024 21:33:10 +0100
changeset 1044
776001e4cc96
parent 985
68754c7de906
permissions
-rw-r--r--

add documentation for string to number conversion functions

issue #532

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 /**
971
cc204fc56c9c rename utils.h to streams.h
Mike Becker <universe@uap-core.de>
parents: 970
diff changeset
30 * \file streams.h
483
929016224c3c add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
31 *
971
cc204fc56c9c rename utils.h to streams.h
Mike Becker <universe@uap-core.de>
parents: 970
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 *
929016224c3c add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
34 * \author Mike Becker
929016224c3c add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
35 * \author Olaf Wintermann
929016224c3c add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
36 * \copyright 2-Clause BSD License
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
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
55 * @param buf a pointer to the copy buffer or \c NULL if a buffer
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
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
57 * @param bufsize the size of the copy buffer - if \p buf is \c NULL you can
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.
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
60 * If this is larger than \p bufsize, the content is copied over multiple
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)
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 971
diff changeset
65 cx_attr_access_r(1)
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 971
diff changeset
66 cx_attr_access_w(2)
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 971
diff changeset
67 cx_attr_access_w(5)
674
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
68 size_t cx_stream_bncopy(
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
69 void *src,
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
70 void *dest,
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
71 cx_read_func rfnc,
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
72 cx_write_func wfnc,
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
73 char *buf,
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
74 size_t bufsize,
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
75 size_t n
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
76 );
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
77
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
78 /**
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
79 * 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
80 *
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
81 * @param src the source stream
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
82 * @param dest the destination stream
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
83 * @param rfnc the read function
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
84 * @param wfnc the write function
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
85 * @param buf a pointer to the copy buffer or \c NULL if a buffer
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
86 * shall be implicitly created on the heap
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
87 * @param bufsize the size of the copy buffer - if \p buf is \c NULL you can
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
88 * 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
89 * @return total number of bytes copied
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 #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
92 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
93
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
94 /**
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
95 * 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
96 *
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
97 * The data is temporarily stored in a stack allocated buffer.
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
98 *
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
99 * @param src the source stream
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
100 * @param dest the destination stream
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
101 * @param rfnc the read function
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
102 * @param wfnc the write function
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
103 * @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
104 * @return total number of bytes copied
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
105 */
985
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 971
diff changeset
106 cx_attr_nonnull
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 971
diff changeset
107 cx_attr_access_r(1)
68754c7de906 major refactoring of attributes
Mike Becker <universe@uap-core.de>
parents: 971
diff changeset
108 cx_attr_access_w(2)
674
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
109 size_t cx_stream_ncopy(
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
110 void *src,
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
111 void *dest,
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
112 cx_read_func rfnc,
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
113 cx_write_func wfnc,
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
114 size_t n
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
115 );
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
116
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
117 /**
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
118 * 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
119 *
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
120 * The data is temporarily stored in a stack allocated buffer.
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
121 *
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
122 * @param src the source stream
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
123 * @param dest the destination stream
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
124 * @param rfnc the read function
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
125 * @param wfnc the write function
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
126 * @return total number of bytes copied
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
127 */
dc514a5d42a5 add stream copy utils - fixes #254
Mike Becker <universe@uap-core.de>
parents: 654
diff changeset
128 #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
129 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
130
929016224c3c add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
131 #ifdef __cplusplus
929016224c3c add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
132 }
929016224c3c add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
133 #endif
929016224c3c add ported UCX buffer implementation
Mike Becker <universe@uap-core.de>
parents:
diff changeset
134
971
cc204fc56c9c rename utils.h to streams.h
Mike Becker <universe@uap-core.de>
parents: 970
diff changeset
135 #endif // UCX_STREAMS_H

mercurial