1 | // Copyright 2011 Google Inc. All Rights Reserved. |
2 | // |
3 | // Redistribution and use in source and binary forms, with or without |
4 | // modification, are permitted provided that the following conditions are |
5 | // met: |
6 | // |
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 |
10 | // copyright notice, this list of conditions and the following disclaimer |
11 | // in the documentation and/or other materials provided with the |
12 | // distribution. |
13 | // * Neither the name of Google Inc. nor the names of its |
14 | // contributors may be used to endorse or promote products derived from |
15 | // this software without specific prior written permission. |
16 | // |
17 | // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS |
18 | // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT |
19 | // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR |
20 | // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT |
21 | // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, |
22 | // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT |
23 | // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, |
24 | // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY |
25 | // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT |
26 | // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE |
27 | // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
28 | |
29 | #ifndef BUTIL_THIRD_PARTY_SNAPPY_SNAPPY_SINKSOURCE_H_ |
30 | #define BUTIL_THIRD_PARTY_SNAPPY_SNAPPY_SINKSOURCE_H_ |
31 | |
32 | #include <stddef.h> |
33 | |
34 | namespace butil { |
35 | namespace snappy { |
36 | |
37 | // A Sink is an interface that consumes a sequence of bytes. |
38 | class Sink { |
39 | public: |
40 | Sink() { } |
41 | virtual ~Sink(); |
42 | |
43 | // Append "bytes[0,n-1]" to this. |
44 | virtual void Append(const char* bytes, size_t n) = 0; |
45 | |
46 | // Returns a writable buffer of the specified length for appending. |
47 | // May return a pointer to the caller-owned scratch buffer which |
48 | // must have at least the indicated length. The returned buffer is |
49 | // only valid until the next operation on this Sink. |
50 | // |
51 | // After writing at most "length" bytes, call Append() with the |
52 | // pointer returned from this function and the number of bytes |
53 | // written. Many Append() implementations will avoid copying |
54 | // bytes if this function returned an internal buffer. |
55 | // |
56 | // If a non-scratch buffer is returned, the caller may only pass a |
57 | // prefix of it to Append(). That is, it is not correct to pass an |
58 | // interior pointer of the returned array to Append(). |
59 | // |
60 | // The default implementation always returns the scratch buffer. |
61 | virtual char* GetAppendBuffer(size_t length, char* scratch); |
62 | |
63 | // For higher performance, Sink implementations can provide custom |
64 | // AppendAndTakeOwnership() and GetAppendBufferVariable() methods. |
65 | // These methods can reduce the number of copies done during |
66 | // compression/decompression. |
67 | |
68 | // Append "bytes[0,n-1] to the sink. Takes ownership of "bytes" |
69 | // and calls the deleter function as (*deleter)(deleter_arg, bytes, n) |
70 | // to free the buffer. deleter function must be non NULL. |
71 | // |
72 | // The default implementation just calls Append and frees "bytes". |
73 | // Other implementations may avoid a copy while appending the buffer. |
74 | virtual void AppendAndTakeOwnership( |
75 | char* bytes, size_t n, void (*deleter)(void*, const char*, size_t), |
76 | void *deleter_arg); |
77 | |
78 | // Returns a writable buffer for appending and writes the buffer's capacity to |
79 | // *allocated_size. Guarantees *allocated_size >= min_size. |
80 | // May return a pointer to the caller-owned scratch buffer which must have |
81 | // scratch_size >= min_size. |
82 | // |
83 | // The returned buffer is only valid until the next operation |
84 | // on this ByteSink. |
85 | // |
86 | // After writing at most *allocated_size bytes, call Append() with the |
87 | // pointer returned from this function and the number of bytes written. |
88 | // Many Append() implementations will avoid copying bytes if this function |
89 | // returned an internal buffer. |
90 | // |
91 | // If the sink implementation allocates or reallocates an internal buffer, |
92 | // it should use the desired_size_hint if appropriate. If a caller cannot |
93 | // provide a reasonable guess at the desired capacity, it should set |
94 | // desired_size_hint = 0. |
95 | // |
96 | // If a non-scratch buffer is returned, the caller may only pass |
97 | // a prefix to it to Append(). That is, it is not correct to pass an |
98 | // interior pointer to Append(). |
99 | // |
100 | // The default implementation always returns the scratch buffer. |
101 | virtual char* GetAppendBufferVariable( |
102 | size_t min_size, size_t desired_size_hint, char* scratch, |
103 | size_t scratch_size, size_t* allocated_size); |
104 | |
105 | private: |
106 | // No copying |
107 | Sink(const Sink&); |
108 | void operator=(const Sink&); |
109 | }; |
110 | |
111 | // A Source is an interface that yields a sequence of bytes |
112 | class Source { |
113 | public: |
114 | Source() { } |
115 | virtual ~Source(); |
116 | |
117 | // Return the number of bytes left to read from the source |
118 | virtual size_t Available() const = 0; |
119 | |
120 | // Peek at the next flat region of the source. Does not reposition |
121 | // the source. The returned region is empty iff Available()==0. |
122 | // |
123 | // Returns a pointer to the beginning of the region and store its |
124 | // length in *len. |
125 | // |
126 | // The returned region is valid until the next call to Skip() or |
127 | // until this object is destroyed, whichever occurs first. |
128 | // |
129 | // The returned region may be larger than Available() (for example |
130 | // if this ByteSource is a view on a substring of a larger source). |
131 | // The caller is responsible for ensuring that it only reads the |
132 | // Available() bytes. |
133 | virtual const char* Peek(size_t* len) = 0; |
134 | |
135 | // Skip the next n bytes. Invalidates any buffer returned by |
136 | // a previous call to Peek(). |
137 | // REQUIRES: Available() >= n |
138 | virtual void Skip(size_t n) = 0; |
139 | |
140 | private: |
141 | // No copying |
142 | Source(const Source&); |
143 | void operator=(const Source&); |
144 | }; |
145 | |
146 | // A Source implementation that yields the contents of a flat array |
147 | class ByteArraySource : public Source { |
148 | public: |
149 | ByteArraySource(const char* p, size_t n) : ptr_(p), left_(n) { } |
150 | virtual ~ByteArraySource(); |
151 | size_t Available() const override; |
152 | const char* Peek(size_t* len) override; |
153 | void Skip(size_t n) override; |
154 | private: |
155 | const char* ptr_; |
156 | size_t left_; |
157 | }; |
158 | |
159 | // A Sink implementation that writes to a flat array without any bound checks. |
160 | class UncheckedByteArraySink : public Sink { |
161 | public: |
162 | explicit UncheckedByteArraySink(char* dest) : dest_(dest) { } |
163 | virtual ~UncheckedByteArraySink(); |
164 | void Append(const char* data, size_t n) override; |
165 | char* GetAppendBuffer(size_t len, char* scratch) override; |
166 | char* GetAppendBufferVariable( |
167 | size_t min_size, size_t desired_size_hint, char* scratch, |
168 | size_t scratch_size, size_t* allocated_size) override; |
169 | void AppendAndTakeOwnership( |
170 | char* bytes, size_t n, void (*deleter)(void*, const char*, size_t), |
171 | void *deleter_arg) override; |
172 | |
173 | // Return the current output pointer so that a caller can see how |
174 | // many bytes were produced. |
175 | // Note: this is not a Sink method. |
176 | char* CurrentDestination() const { return dest_; } |
177 | private: |
178 | char* dest_; |
179 | }; |
180 | |
181 | } // namespace snappy |
182 | } // namespace butil |
183 | |
184 | #endif // BUTIL_THIRD_PARTY_SNAPPY_SNAPPY_SINKSOURCE_H_ |
185 | |