comparison: docs/Writerside/topics/streams.h.md
docs/Writerside/topics/streams.h.md
- branch
- docs/3.1
- changeset 1145
- 1a8fe7b7dd8a
- parent 1143
- 0559812df10c
- child 1147
- 52802c36b261
equal
deleted
inserted
replaced
| 1144:b23d07fff6ca | 1145:1a8fe7b7dd8a |
|---|---|
| 1 # Stream Operations | 1 # Data Streams |
| 2 | 2 |
| 3 UCX provides some utilities for routine tasks. | 3 Stream copy functions provide a way to copy all - or a limited amount of - data from one stream to another. |
| 4 Since the read/write functions of a [UCX buffer](buffer.h.md) are fully compatible with stream read/write functions, | |
| 5 you can, for example, easily transfer data from a file or network stream to a UCX buffer or vice versa. | |
| 4 | 6 |
| 5 The most useful utilities are the *stream copy* functions, which provide a simple way to copy all - or a | 7 ## Overview |
| 6 bounded amount of - data from one stream to another. Since the read/write functions of a UCX buffer are | 8 ```C |
| 7 fully compatible with stream read/write functions, you can easily transfer data from file or network streams to | 9 #include <cx/streams.h> |
| 8 a UCX buffer or vice-versa. | |
| 9 | 10 |
| 10 The following example shows, how easy it is to read the contents of a file into a buffer: | 11 size_t cx_stream_copy( |
| 12 void *src, void *dest, | |
| 13 cx_read_func rfnc, cx_write_func wfnc | |
| 14 ); | |
| 15 size_t cx_stream_ncopy( | |
| 16 void *src, void *dest, | |
| 17 cx_read_func rfnc, cx_write_func wfnc, | |
| 18 size_t n | |
| 19 ); | |
| 20 | |
| 21 size_t cx_stream_bcopy( | |
| 22 void *src, void *dest, | |
| 23 cx_read_func rfnc, cx_write_func wfnc, | |
| 24 char *buf, size_t bufsize | |
| 25 ); | |
| 26 size_t cx_stream_bncopy( | |
| 27 void *src, void *dest, | |
| 28 cx_read_func rfnc, cx_write_func wfnc, | |
| 29 char *buf, size_t bufsize, | |
| 30 size_t n | |
| 31 ); | |
| 32 ``` | |
| 33 | |
| 34 ## Description | |
| 35 | |
| 36 All functions in the stream copy family use the `rfnc` to read data from `src` | |
| 37 and use the `wfnc` to write the data to `dest`. | |
| 38 | |
| 39 The `cx_stream_copy()` function always uses internal stack memory as a temporary buffer for the read bytes. | |
| 40 The `cx_stream_bcopy()` function uses either a pre-initialized buffer `buf` of length `bufsize` | |
| 41 or, if `buf` is `NULL`, an internal heap-allocated buffer. | |
| 42 | |
| 43 The `cx_stream_ncopy()` function behaves like `cx_stream_copy()` except, that it reads at most `n` bytes | |
| 44 (and the same is true for `cx_stream_bncopy()` and `cx_stream_bcopy()`). | |
| 45 | |
| 46 | |
| 47 <warning> | |
| 48 When you are reading from a stream where you cannot track the position, there is the possibility that | |
| 49 data gets lost when the destination does not accept all the bytes read from the source. | |
| 50 While the stream copy functions do report how many bytes were <emphasis>successfully</emphasis> copied | |
| 51 to the destination, this might - in certain cases - not be the exact number of read items. | |
| 52 | |
| 53 To mitigate the risk, you should make sure that the destination can always accept all read bytes and | |
| 54 a possible bottleneck is only introduced by the source. | |
| 55 </warning> | |
| 56 | |
| 57 > The size of the internal _stack_ buffer in `cx_stream_copy()` and `cx_stream_ncopy()` can be | |
| 58 > set during compilation via the `CX_STREAM_COPY_BUF_SIZE` macro. | |
| 59 > Similarly, the size for the implicitly allocated _heap_ buffer in can be | |
| 60 > configured via the `CX_STREAM_BCOPY_BUF_SIZE` macro. | |
| 61 > Refer to the [build instructions](install.md#compile-time-options) for the details. | |
| 62 | |
| 63 ## Example | |
| 64 | |
| 65 The following example shows, how to read the contents of a file into a buffer: | |
| 11 ```c | 66 ```c |
| 12 FILE *inputfile = fopen(infilename, "r"); | 67 FILE *inputfile = fopen(infilename, "r"); |
| 13 if (inputfile) { | 68 if (inputfile) { |
| 14 CxBuffer fbuf; | 69 CxBuffer fbuf; |
| 15 cxBufferInit(&fbuf, NULL, 4096, NULL, CX_BUFFER_AUTO_EXTEND); | 70 cxBufferInit(&fbuf, NULL, 4096, NULL, CX_BUFFER_AUTO_EXTEND); |
| 27 fclose(fout); | 82 fclose(fout); |
| 28 } | 83 } |
| 29 } | 84 } |
| 30 ``` | 85 ``` |
| 31 | 86 |
| 32 ## Undocumented Symbols (TODO) | 87 |
| 33 ### cx_stream_bncopy | 88 <seealso> |
| 34 ### cx_stream_ncopy | 89 <category ref="apidoc"> |
| 90 <a href="https://ucx.sourceforge.io/api/streams_8h.html">streams.h</a> | |
| 91 </category> | |
| 92 </seealso> |
