1 /*
2 * Copyright (c) 2009-2022, Google LLC
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions are met:
7 * * Redistributions of source code must retain the above copyright
8 * notice, this list of conditions and the following disclaimer.
9 * * Redistributions in binary form must reproduce the above copyright
10 * notice, this list of conditions and the following disclaimer in the
11 * documentation and/or other materials provided with the distribution.
12 * * Neither the name of Google LLC nor the
13 * names of its contributors may be used to endorse or promote products
14 * derived from this software without specific prior written permission.
15 *
16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
17 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 * ARE DISCLAIMED. IN NO EVENT SHALL Google LLC BE LIABLE FOR ANY DIRECT,
20 * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
21 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
22 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
23 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
24 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
25 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26 */
27
28 #ifndef UPB_IO_ZERO_COPY_OUTPUT_STREAM_H_
29 #define UPB_IO_ZERO_COPY_OUTPUT_STREAM_H_
30
31 #include "upb/base/status.h"
32
33 // Must be last.
34 #include "upb/port/def.inc"
35
36 #ifdef __cplusplus
37 extern "C" {
38 #endif
39
40 typedef struct upb_ZeroCopyOutputStream upb_ZeroCopyOutputStream;
41
42 typedef struct {
43 // Obtains a buffer into which data can be written. Any data written
44 // into this buffer will eventually (maybe instantly, maybe later on)
45 // be written to the output.
46 //
47 // Preconditions:
48 // "count" and "status" are not NULL.
49 //
50 // Postconditions:
51 // All errors are permanent. If an error occurs then:
52 // - NULL will be returned to the caller.
53 // - *count will be set to zero.
54 // - *status will be set to the error.
55 // EOF is permanent. If EOF is reached then:
56 // - NULL will be returned to the caller.
57 // - *count will be set to zero.
58 // - *status will not be touched.
59 // Otherwise:
60 // - The returned value will point to a buffer containing the bytes read.
61 // - *count will be set to the number of bytes read.
62 // - *status will not be touched.
63 //
64 // Ownership of this buffer remains with the stream, and the buffer
65 // remains valid only until some other method of the stream is called
66 // or the stream is destroyed.
67 //
68 // Any data which the caller stores in this buffer will eventually be
69 // written to the output (unless BackUp() is called).
70 void* (*Next)(struct upb_ZeroCopyOutputStream* z, size_t* count,
71 upb_Status* status);
72
73 // Backs up a number of bytes, so that the end of the last buffer returned
74 // by Next() is not actually written. This is needed when you finish
75 // writing all the data you want to write, but the last buffer was bigger
76 // than you needed. You don't want to write a bunch of garbage after the
77 // end of your data, so you use BackUp() to back up.
78 //
79 // Preconditions:
80 // * The last method called must have been Next().
81 // * count must be less than or equal to the size of the last buffer
82 // returned by Next().
83 // * The caller must not have written anything to the last "count" bytes
84 // of that buffer.
85 //
86 // Postconditions:
87 // * The last "count" bytes of the last buffer returned by Next() will be
88 // ignored.
89 //
90 // This method can be called with `count = 0` to finalize (flush) any
91 // previously returned buffer. For example, a file output stream can
92 // flush buffers returned from a previous call to Next() upon such
93 // BackUp(0) invocations. ZeroCopyOutputStream callers should always
94 // invoke BackUp() after a final Next() call, even if there is no
95 // excess buffer data to be backed up to indicate a flush point.
96 void (*BackUp)(struct upb_ZeroCopyOutputStream* z, size_t count);
97
98 // Returns the total number of bytes written since this object was created.
99 size_t (*ByteCount)(const struct upb_ZeroCopyOutputStream* z);
100 } _upb_ZeroCopyOutputStream_VTable;
101
102 struct upb_ZeroCopyOutputStream {
103 const _upb_ZeroCopyOutputStream_VTable* vtable;
104 };
105
upb_ZeroCopyOutputStream_Next(upb_ZeroCopyOutputStream * z,size_t * count,upb_Status * status)106 UPB_INLINE void* upb_ZeroCopyOutputStream_Next(upb_ZeroCopyOutputStream* z,
107 size_t* count,
108 upb_Status* status) {
109 void* out = z->vtable->Next(z, count, status);
110 UPB_ASSERT((out == NULL) == (*count == 0));
111 return out;
112 }
113
upb_ZeroCopyOutputStream_BackUp(upb_ZeroCopyOutputStream * z,size_t count)114 UPB_INLINE void upb_ZeroCopyOutputStream_BackUp(upb_ZeroCopyOutputStream* z,
115 size_t count) {
116 return z->vtable->BackUp(z, count);
117 }
118
119 UPB_INLINE size_t
upb_ZeroCopyOutputStream_ByteCount(const upb_ZeroCopyOutputStream * z)120 upb_ZeroCopyOutputStream_ByteCount(const upb_ZeroCopyOutputStream* z) {
121 return z->vtable->ByteCount(z);
122 }
123
124 #ifdef __cplusplus
125 } /* extern "C" */
126 #endif
127
128 #include "upb/port/undef.inc"
129
130 #endif /* UPB_IO_ZERO_COPY_OUTPUT_STREAM_H_ */
131