Line data Source code
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 THIRD_PARTY_SNAPPY_SNAPPY_SINKSOURCE_H_
30 : #define THIRD_PARTY_SNAPPY_SNAPPY_SINKSOURCE_H_
31 :
32 : #include <stddef.h>
33 :
34 : namespace snappy {
35 :
36 : // A Sink is an interface that consumes a sequence of bytes.
37 : class Sink {
38 : public:
39 0 : Sink() { }
40 : virtual ~Sink();
41 :
42 : // Append "bytes[0,n-1]" to this.
43 : virtual void Append(const char* bytes, size_t n) = 0;
44 :
45 : // Returns a writable buffer of the specified length for appending.
46 : // May return a pointer to the caller-owned scratch buffer which
47 : // must have at least the indicated length. The returned buffer is
48 : // only valid until the next operation on this Sink.
49 : //
50 : // After writing at most "length" bytes, call Append() with the
51 : // pointer returned from this function and the number of bytes
52 : // written. Many Append() implementations will avoid copying
53 : // bytes if this function returned an internal buffer.
54 : //
55 : // If a non-scratch buffer is returned, the caller may only pass a
56 : // prefix of it to Append(). That is, it is not correct to pass an
57 : // interior pointer of the returned array to Append().
58 : //
59 : // The default implementation always returns the scratch buffer.
60 : virtual char* GetAppendBuffer(size_t length, char* scratch);
61 :
62 : // For higher performance, Sink implementations can provide custom
63 : // AppendAndTakeOwnership() and GetAppendBufferVariable() methods.
64 : // These methods can reduce the number of copies done during
65 : // compression/decompression.
66 :
67 : // Append "bytes[0,n-1] to the sink. Takes ownership of "bytes"
68 : // and calls the deleter function as (*deleter)(deleter_arg, bytes, n)
69 : // to free the buffer. deleter function must be non NULL.
70 : //
71 : // The default implementation just calls Append and frees "bytes".
72 : // Other implementations may avoid a copy while appending the buffer.
73 : virtual void AppendAndTakeOwnership(
74 : char* bytes, size_t n, void (*deleter)(void*, const char*, size_t),
75 : void *deleter_arg);
76 :
77 : // Returns a writable buffer for appending and writes the buffer's capacity to
78 : // *allocated_size. Guarantees *allocated_size >= min_size.
79 : // May return a pointer to the caller-owned scratch buffer which must have
80 : // scratch_size >= min_size.
81 : //
82 : // The returned buffer is only valid until the next operation
83 : // on this ByteSink.
84 : //
85 : // After writing at most *allocated_size bytes, call Append() with the
86 : // pointer returned from this function and the number of bytes written.
87 : // Many Append() implementations will avoid copying bytes if this function
88 : // returned an internal buffer.
89 : //
90 : // If the sink implementation allocates or reallocates an internal buffer,
91 : // it should use the desired_size_hint if appropriate. If a caller cannot
92 : // provide a reasonable guess at the desired capacity, it should set
93 : // desired_size_hint = 0.
94 : //
95 : // If a non-scratch buffer is returned, the caller may only pass
96 : // a prefix to it to Append(). That is, it is not correct to pass an
97 : // interior pointer to Append().
98 : //
99 : // The default implementation always returns the scratch buffer.
100 : virtual char* GetAppendBufferVariable(
101 : size_t min_size, size_t desired_size_hint, char* scratch,
102 : size_t scratch_size, size_t* allocated_size);
103 :
104 : private:
105 : // No copying
106 : Sink(const Sink&);
107 : void operator=(const Sink&);
108 : };
109 :
110 : // A Source is an interface that yields a sequence of bytes
111 : class Source {
112 : public:
113 0 : Source() { }
114 : virtual ~Source();
115 :
116 : // Return the number of bytes left to read from the source
117 : virtual size_t Available() const = 0;
118 :
119 : // Peek at the next flat region of the source. Does not reposition
120 : // the source. The returned region is empty iff Available()==0.
121 : //
122 : // Returns a pointer to the beginning of the region and store its
123 : // length in *len.
124 : //
125 : // The returned region is valid until the next call to Skip() or
126 : // until this object is destroyed, whichever occurs first.
127 : //
128 : // The returned region may be larger than Available() (for example
129 : // if this ByteSource is a view on a substring of a larger source).
130 : // The caller is responsible for ensuring that it only reads the
131 : // Available() bytes.
132 : virtual const char* Peek(size_t* len) = 0;
133 :
134 : // Skip the next n bytes. Invalidates any buffer returned by
135 : // a previous call to Peek().
136 : // REQUIRES: Available() >= n
137 : virtual void Skip(size_t n) = 0;
138 :
139 : private:
140 : // No copying
141 : Source(const Source&);
142 : void operator=(const Source&);
143 : };
144 :
145 : // A Source implementation that yields the contents of a flat array
146 : class ByteArraySource : public Source {
147 : public:
148 0 : ByteArraySource(const char* p, size_t n) : ptr_(p), left_(n) { }
149 : virtual ~ByteArraySource();
150 : virtual size_t Available() const;
151 : virtual const char* Peek(size_t* len);
152 : virtual void Skip(size_t n);
153 : private:
154 : const char* ptr_;
155 : size_t left_;
156 : };
157 :
158 : // A Sink implementation that writes to a flat array without any bound checks.
159 : class UncheckedByteArraySink : public Sink {
160 : public:
161 0 : explicit UncheckedByteArraySink(char* dest) : dest_(dest) { }
162 : virtual ~UncheckedByteArraySink();
163 : virtual void Append(const char* data, size_t n);
164 : virtual char* GetAppendBuffer(size_t len, char* scratch);
165 : virtual char* GetAppendBufferVariable(
166 : size_t min_size, size_t desired_size_hint, char* scratch,
167 : size_t scratch_size, size_t* allocated_size);
168 : virtual void AppendAndTakeOwnership(
169 : char* bytes, size_t n, void (*deleter)(void*, const char*, size_t),
170 : void *deleter_arg);
171 :
172 : // Return the current output pointer so that a caller can see how
173 : // many bytes were produced.
174 : // Note: this is not a Sink method.
175 0 : char* CurrentDestination() const { return dest_; }
176 : private:
177 : char* dest_;
178 : };
179 :
180 : } // namespace snappy
181 :
182 : #endif // THIRD_PARTY_SNAPPY_SNAPPY_SINKSOURCE_H_
|
