1 // Protocol Buffers - Google's data interchange format
2 // Copyright 2023 Google LLC. All rights reserved.
3 //
4 // Use of this source code is governed by a BSD-style
5 // license that can be found in the LICENSE file or at
6 // https://developers.google.com/open-source/licenses/bsd
7
8 #ifndef UPB_IO_ZERO_COPY_OUTPUT_STREAM_H_
9 #define UPB_IO_ZERO_COPY_OUTPUT_STREAM_H_
10
11 #include "upb/base/status.h"
12
13 // Must be last.
14 #include "upb/port/def.inc"
15
16 #ifdef __cplusplus
17 extern "C" {
18 #endif
19
20 typedef struct upb_ZeroCopyOutputStream upb_ZeroCopyOutputStream;
21
22 typedef struct {
23 // Obtains a buffer into which data can be written. Any data written
24 // into this buffer will eventually (maybe instantly, maybe later on)
25 // be written to the output.
26 //
27 // Preconditions:
28 // "count" and "status" are not NULL.
29 //
30 // Postconditions:
31 // All errors are permanent. If an error occurs then:
32 // - NULL will be returned to the caller.
33 // - *count will be set to zero.
34 // - *status will be set to the error.
35 // EOF is permanent. If EOF is reached then:
36 // - NULL will be returned to the caller.
37 // - *count will be set to zero.
38 // - *status will not be touched.
39 // Otherwise:
40 // - The returned value will point to a buffer containing the bytes read.
41 // - *count will be set to the number of bytes read.
42 // - *status will not be touched.
43 //
44 // Ownership of this buffer remains with the stream, and the buffer
45 // remains valid only until some other method of the stream is called
46 // or the stream is destroyed.
47 //
48 // Any data which the caller stores in this buffer will eventually be
49 // written to the output (unless BackUp() is called).
50 void* (*Next)(struct upb_ZeroCopyOutputStream* z, size_t* count,
51 upb_Status* status);
52
53 // Backs up a number of bytes, so that the end of the last buffer returned
54 // by Next() is not actually written. This is needed when you finish
55 // writing all the data you want to write, but the last buffer was bigger
56 // than you needed. You don't want to write a bunch of garbage after the
57 // end of your data, so you use BackUp() to back up.
58 //
59 // Preconditions:
60 // * The last method called must have been Next().
61 // * count must be less than or equal to the size of the last buffer
62 // returned by Next().
63 // * The caller must not have written anything to the last "count" bytes
64 // of that buffer.
65 //
66 // Postconditions:
67 // * The last "count" bytes of the last buffer returned by Next() will be
68 // ignored.
69 //
70 // This method can be called with `count = 0` to finalize (flush) any
71 // previously returned buffer. For example, a file output stream can
72 // flush buffers returned from a previous call to Next() upon such
73 // BackUp(0) invocations. ZeroCopyOutputStream callers should always
74 // invoke BackUp() after a final Next() call, even if there is no
75 // excess buffer data to be backed up to indicate a flush point.
76 void (*BackUp)(struct upb_ZeroCopyOutputStream* z, size_t count);
77
78 // Returns the total number of bytes written since this object was created.
79 size_t (*ByteCount)(const struct upb_ZeroCopyOutputStream* z);
80 } _upb_ZeroCopyOutputStream_VTable;
81
82 struct upb_ZeroCopyOutputStream {
83 const _upb_ZeroCopyOutputStream_VTable* vtable;
84 };
85
upb_ZeroCopyOutputStream_Next(upb_ZeroCopyOutputStream * z,size_t * count,upb_Status * status)86 UPB_INLINE void* upb_ZeroCopyOutputStream_Next(upb_ZeroCopyOutputStream* z,
87 size_t* count,
88 upb_Status* status) {
89 void* out = z->vtable->Next(z, count, status);
90 UPB_ASSERT((out == NULL) == (*count == 0));
91 return out;
92 }
93
upb_ZeroCopyOutputStream_BackUp(upb_ZeroCopyOutputStream * z,size_t count)94 UPB_INLINE void upb_ZeroCopyOutputStream_BackUp(upb_ZeroCopyOutputStream* z,
95 size_t count) {
96 return z->vtable->BackUp(z, count);
97 }
98
99 UPB_INLINE size_t
upb_ZeroCopyOutputStream_ByteCount(const upb_ZeroCopyOutputStream * z)100 upb_ZeroCopyOutputStream_ByteCount(const upb_ZeroCopyOutputStream* z) {
101 return z->vtable->ByteCount(z);
102 }
103
104 #ifdef __cplusplus
105 } /* extern "C" */
106 #endif
107
108 #include "upb/port/undef.inc"
109
110 #endif /* UPB_IO_ZERO_COPY_OUTPUT_STREAM_H_ */
111