io.h 15.2 KB
Newer Older
Kenton Varda's avatar
Kenton Varda committed
1 2
// Copyright (c) 2013-2014 Sandstorm Development Group, Inc. and contributors
// Licensed under the MIT License:
3
//
Kenton Varda's avatar
Kenton Varda committed
4 5 6 7 8 9
// Permission is hereby granted, free of charge, to any person obtaining a copy
// of this software and associated documentation files (the "Software"), to deal
// in the Software without restriction, including without limitation the rights
// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
// copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
10
//
Kenton Varda's avatar
Kenton Varda committed
11 12
// The above copyright notice and this permission notice shall be included in
// all copies or substantial portions of the Software.
13
//
Kenton Varda's avatar
Kenton Varda committed
14 15 16 17 18 19 20
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
// THE SOFTWARE.
21

22 23
#ifndef KJ_IO_H_
#define KJ_IO_H_
24

25 26 27 28
#if defined(__GNUC__) && !KJ_HEADER_WARNINGS
#pragma GCC system_header
#endif

Kenton Varda's avatar
Kenton Varda committed
29
#include <stddef.h>
Kenton Varda's avatar
Kenton Varda committed
30
#include "common.h"
31
#include "array.h"
32
#include "exception.h"
33

34
namespace kj {
35 36 37 38 39 40

// =======================================================================================
// Abstract interfaces

class InputStream {
public:
41
  virtual ~InputStream() noexcept(false);
42

43
  size_t read(void* buffer, size_t minBytes, size_t maxBytes);
44
  // Reads at least minBytes and at most maxBytes, copying them into the given buffer.  Returns
45
  // the size read.  Throws an exception on errors.  Implemented in terms of tryRead().
46 47 48 49 50 51 52
  //
  // maxBytes is the number of bytes the caller really wants, but minBytes is the minimum amount
  // needed by the caller before it can start doing useful processing.  If the stream returns less
  // than maxBytes, the caller will usually call read() again later to get the rest.  Returning
  // less than maxBytes is useful when it makes sense for the caller to parallelize processing
  // with I/O.
  //
53 54 55 56
  // Never blocks if minBytes is zero.  If minBytes is zero and maxBytes is non-zero, this may
  // attempt a non-blocking read or may just return zero.  To force a read, use a non-zero minBytes.
  // To detect EOF without throwing an exception, use tryRead().
  //
57
  // If the InputStream can't produce minBytes, it MUST throw an exception, as the caller is not
58 59
  // expected to understand how to deal with partial reads.

60 61 62
  virtual size_t tryRead(void* buffer, size_t minBytes, size_t maxBytes) = 0;
  // Like read(), but may return fewer than minBytes on EOF.

63 64 65 66 67 68 69 70 71 72
  inline void read(void* buffer, size_t bytes) { read(buffer, bytes, bytes); }
  // Convenience method for reading an exact number of bytes.

  virtual void skip(size_t bytes);
  // Skips past the given number of bytes, discarding them.  The default implementation read()s
  // into a scratch buffer.
};

class OutputStream {
public:
73
  virtual ~OutputStream() noexcept(false);
74 75 76 77

  virtual void write(const void* buffer, size_t size) = 0;
  // Always writes the full size.  Throws exception on error.

78
  virtual void write(ArrayPtr<const ArrayPtr<const byte>> pieces);
79 80 81 82 83 84 85 86 87 88 89 90
  // Equivalent to write()ing each byte array in sequence, which is what the default implementation
  // does.  Override if you can do something better, e.g. use writev() to do the write in a single
  // syscall.
};

class BufferedInputStream: public InputStream {
  // An input stream which buffers some bytes in memory to reduce system call overhead.
  // - OR -
  // An input stream that actually reads from some in-memory data structure and wants to give its
  // caller a direct pointer to that memory to potentially avoid a copy.

public:
91
  virtual ~BufferedInputStream() noexcept(false);
92

93
  ArrayPtr<const byte> getReadBuffer();
94 95
  // Get a direct pointer into the read buffer, which contains the next bytes in the input.  If the
  // caller consumes any bytes, it should then call skip() to indicate this.  This always returns a
96 97 98 99
  // non-empty buffer or throws an exception.  Implemented in terms of tryGetReadBuffer().

  virtual ArrayPtr<const byte> tryGetReadBuffer() = 0;
  // Like getReadBuffer() but may return an empty buffer on EOF.
100 101 102 103 104 105 106 107 108
};

class BufferedOutputStream: public OutputStream {
  // An output stream which buffers some bytes in memory to reduce system call overhead.
  // - OR -
  // An output stream that actually writes into some in-memory data structure and wants to give its
  // caller a direct pointer to that memory to potentially avoid a copy.

public:
109
  virtual ~BufferedOutputStream() noexcept(false);
110

111
  virtual ArrayPtr<byte> getWriteBuffer() = 0;
112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129
  // Get a direct pointer into the write buffer.  The caller may choose to fill in some prefix of
  // this buffer and then pass it to write(), in which case write() may avoid a copy.  It is
  // incorrect to pass to write any slice of this buffer which is not a prefix.
};

// =======================================================================================
// Buffered streams implemented as wrappers around regular streams

class BufferedInputStreamWrapper: public BufferedInputStream {
  // Implements BufferedInputStream in terms of an InputStream.
  //
  // Note that the underlying stream's position is unpredictable once the wrapper is destroyed,
  // unless the entire stream was consumed.  To read a predictable number of bytes in a buffered
  // way without going over, you'd need this wrapper to wrap some other wrapper which itself
  // implements an artificial EOF at the desired point.  Such a stream should be trivial to write
  // but is not provided by the library at this time.

public:
130
  explicit BufferedInputStreamWrapper(InputStream& inner, ArrayPtr<byte> buffer = nullptr);
131 132 133 134 135 136 137
  // Creates a buffered stream wrapping the given non-buffered stream.  No guarantee is made about
  // the position of the inner stream after a buffered wrapper has been created unless the entire
  // input is read.
  //
  // If the second parameter is non-null, the stream uses the given buffer instead of allocating
  // its own.  This may improve performance if the buffer can be reused.

138
  KJ_DISALLOW_COPY(BufferedInputStreamWrapper);
139
  ~BufferedInputStreamWrapper() noexcept(false);
140 141

  // implements BufferedInputStream ----------------------------------
142 143
  ArrayPtr<const byte> tryGetReadBuffer() override;
  size_t tryRead(void* buffer, size_t minBytes, size_t maxBytes) override;
144 145 146 147
  void skip(size_t bytes) override;

private:
  InputStream& inner;
148 149 150
  Array<byte> ownedBuffer;
  ArrayPtr<byte> buffer;
  ArrayPtr<byte> bufferAvailable;
151 152 153 154 155 156 157
};

class BufferedOutputStreamWrapper: public BufferedOutputStream {
  // Implements BufferedOutputStream in terms of an OutputStream.  Note that writes to the
  // underlying stream may be delayed until flush() is called or the wrapper is destroyed.

public:
158
  explicit BufferedOutputStreamWrapper(OutputStream& inner, ArrayPtr<byte> buffer = nullptr);
159 160 161 162 163
  // Creates a buffered stream wrapping the given non-buffered stream.
  //
  // If the second parameter is non-null, the stream uses the given buffer instead of allocating
  // its own.  This may improve performance if the buffer can be reused.

164
  KJ_DISALLOW_COPY(BufferedOutputStreamWrapper);
165
  ~BufferedOutputStreamWrapper() noexcept(false);
166 167 168 169 170 171 172

  void flush();
  // Force the wrapper to write any remaining bytes in its buffer to the inner stream.  Note that
  // this only flushes this object's buffer; this object has no idea how to flush any other buffers
  // that may be present in the underlying stream.

  // implements BufferedOutputStream ---------------------------------
173
  ArrayPtr<byte> getWriteBuffer() override;
174 175 176 177
  void write(const void* buffer, size_t size) override;

private:
  OutputStream& inner;
178 179
  Array<byte> ownedBuffer;
  ArrayPtr<byte> buffer;
180
  byte* bufferPos;
181
  UnwindDetector unwindDetector;
182 183 184 185 186 187 188
};

// =======================================================================================
// Array I/O

class ArrayInputStream: public BufferedInputStream {
public:
189
  explicit ArrayInputStream(ArrayPtr<const byte> array);
190
  KJ_DISALLOW_COPY(ArrayInputStream);
191
  ~ArrayInputStream() noexcept(false);
192 193

  // implements BufferedInputStream ----------------------------------
194 195
  ArrayPtr<const byte> tryGetReadBuffer() override;
  size_t tryRead(void* buffer, size_t minBytes, size_t maxBytes) override;
196 197 198
  void skip(size_t bytes) override;

private:
199
  ArrayPtr<const byte> array;
200 201 202 203
};

class ArrayOutputStream: public BufferedOutputStream {
public:
204
  explicit ArrayOutputStream(ArrayPtr<byte> array);
205
  KJ_DISALLOW_COPY(ArrayOutputStream);
206
  ~ArrayOutputStream() noexcept(false);
207

208
  ArrayPtr<byte> getArray() {
209
    // Get the portion of the array which has been filled in.
210
    return arrayPtr(array.begin(), fillPos);
211 212 213
  }

  // implements BufferedInputStream ----------------------------------
214
  ArrayPtr<byte> getWriteBuffer() override;
215 216 217
  void write(const void* buffer, size_t size) override;

private:
218
  ArrayPtr<byte> array;
219 220 221
  byte* fillPos;
};

222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243
class VectorOutputStream: public BufferedOutputStream {
public:
  explicit VectorOutputStream(size_t initialCapacity = 4096);
  KJ_DISALLOW_COPY(VectorOutputStream);
  ~VectorOutputStream() noexcept(false);

  ArrayPtr<byte> getArray() {
    // Get the portion of the array which has been filled in.
    return arrayPtr(vector.begin(), fillPos);
  }

  // implements BufferedInputStream ----------------------------------
  ArrayPtr<byte> getWriteBuffer() override;
  void write(const void* buffer, size_t size) override;

private:
  Array<byte> vector;
  byte* fillPos;

  void grow(size_t minSize);
};

244 245 246 247 248 249 250 251 252 253 254 255 256 257
// =======================================================================================
// File descriptor I/O

class AutoCloseFd {
  // A wrapper around a file descriptor which automatically closes the descriptor when destroyed.
  // The wrapper supports move construction for transferring ownership of the descriptor.  If
  // close() returns an error, the destructor throws an exception, UNLESS the destructor is being
  // called during unwind from another exception, in which case the close error is ignored.
  //
  // If your code is not exception-safe, you should not use AutoCloseFd.  In this case you will
  // have to call close() yourself and handle errors appropriately.

public:
  inline AutoCloseFd(): fd(-1) {}
Kenton Varda's avatar
Kenton Varda committed
258
  inline AutoCloseFd(decltype(nullptr)): fd(-1) {}
259
  inline explicit AutoCloseFd(int fd): fd(fd) {}
260
  inline AutoCloseFd(AutoCloseFd&& other) noexcept: fd(other.fd) { other.fd = -1; }
261
  KJ_DISALLOW_COPY(AutoCloseFd);
262
  ~AutoCloseFd() noexcept(false);
263

264 265 266 267 268 269 270 271 272 273 274 275
  inline AutoCloseFd& operator=(AutoCloseFd&& other) {
    AutoCloseFd old(kj::mv(*this));
    fd = other.fd;
    other.fd = -1;
    return *this;
  }

  inline AutoCloseFd& operator=(decltype(nullptr)) {
    AutoCloseFd old(kj::mv(*this));
    return *this;
  }

276 277
  inline operator int() const { return fd; }
  inline int get() const { return fd; }
278

279 280 281 282
  operator bool() const = delete;
  // Deleting this operator prevents accidental use in boolean contexts, which
  // the int conversion operator above would otherwise allow.

Kenton Varda's avatar
Kenton Varda committed
283 284
  inline bool operator==(decltype(nullptr)) { return fd < 0; }
  inline bool operator!=(decltype(nullptr)) { return fd >= 0; }
285 286 287

private:
  int fd;
288
  UnwindDetector unwindDetector;
289 290
};

291 292 293 294 295
inline auto KJ_STRINGIFY(const AutoCloseFd& fd)
    -> decltype(kj::toCharSequence(implicitCast<int>(fd))) {
  return kj::toCharSequence(implicitCast<int>(fd));
}

296 297 298 299
class FdInputStream: public InputStream {
  // An InputStream wrapping a file descriptor.

public:
300
  explicit FdInputStream(int fd): fd(fd) {}
Kenton Varda's avatar
Kenton Varda committed
301
  explicit FdInputStream(AutoCloseFd fd): fd(fd), autoclose(mv(fd)) {}
302
  KJ_DISALLOW_COPY(FdInputStream);
303
  ~FdInputStream() noexcept(false);
304

305
  size_t tryRead(void* buffer, size_t minBytes, size_t maxBytes) override;
306

307 308
  inline int getFd() const { return fd; }

309 310 311 312 313 314 315 316 317
private:
  int fd;
  AutoCloseFd autoclose;
};

class FdOutputStream: public OutputStream {
  // An OutputStream wrapping a file descriptor.

public:
318
  explicit FdOutputStream(int fd): fd(fd) {}
Kenton Varda's avatar
Kenton Varda committed
319
  explicit FdOutputStream(AutoCloseFd fd): fd(fd), autoclose(mv(fd)) {}
320
  KJ_DISALLOW_COPY(FdOutputStream);
321
  ~FdOutputStream() noexcept(false);
322 323

  void write(const void* buffer, size_t size) override;
324
  void write(ArrayPtr<const ArrayPtr<const byte>> pieces) override;
325

326 327
  inline int getFd() const { return fd; }

328 329 330 331 332
private:
  int fd;
  AutoCloseFd autoclose;
};

333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416
// =======================================================================================
// Win32 Handle I/O

#ifdef _WIN32

class AutoCloseHandle {
  // A wrapper around a Win32 HANDLE which automatically closes the handle when destroyed.
  // The wrapper supports move construction for transferring ownership of the handle.  If
  // CloseHandle() returns an error, the destructor throws an exception, UNLESS the destructor is
  // being called during unwind from another exception, in which case the close error is ignored.
  //
  // If your code is not exception-safe, you should not use AutoCloseHandle.  In this case you will
  // have to call close() yourself and handle errors appropriately.

public:
  inline AutoCloseHandle(): handle((void*)-1) {}
  inline AutoCloseHandle(decltype(nullptr)): handle((void*)-1) {}
  inline explicit AutoCloseHandle(void* handle): handle(handle) {}
  inline AutoCloseHandle(AutoCloseHandle&& other) noexcept: handle(other.handle) {
    other.handle = (void*)-1;
  }
  KJ_DISALLOW_COPY(AutoCloseHandle);
  ~AutoCloseHandle() noexcept(false);

  inline AutoCloseHandle& operator=(AutoCloseHandle&& other) {
    AutoCloseHandle old(kj::mv(*this));
    handle = other.handle;
    other.handle = (void*)-1;
    return *this;
  }

  inline AutoCloseHandle& operator=(decltype(nullptr)) {
    AutoCloseHandle old(kj::mv(*this));
    return *this;
  }

  inline operator void*() const { return handle; }
  inline void* get() const { return handle; }

  operator bool() const = delete;
  // Deleting this operator prevents accidental use in boolean contexts, which
  // the void* conversion operator above would otherwise allow.

  inline bool operator==(decltype(nullptr)) { return handle != (void*)-1; }
  inline bool operator!=(decltype(nullptr)) { return handle == (void*)-1; }

private:
  void* handle;  // -1 (aka INVALID_HANDLE_VALUE) if not valid.
};

class HandleInputStream: public InputStream {
  // An InputStream wrapping a Win32 HANDLE.

public:
  explicit HandleInputStream(void* handle): handle(handle) {}
  explicit HandleInputStream(AutoCloseHandle handle): handle(handle), autoclose(mv(handle)) {}
  KJ_DISALLOW_COPY(HandleInputStream);
  ~HandleInputStream() noexcept(false);

  size_t tryRead(void* buffer, size_t minBytes, size_t maxBytes) override;

private:
  void* handle;
  AutoCloseHandle autoclose;
};

class HandleOutputStream: public OutputStream {
  // An OutputStream wrapping a Win32 HANDLE.

public:
  explicit HandleOutputStream(void* handle): handle(handle) {}
  explicit HandleOutputStream(AutoCloseHandle handle): handle(handle), autoclose(mv(handle)) {}
  KJ_DISALLOW_COPY(HandleOutputStream);
  ~HandleOutputStream() noexcept(false);

  void write(const void* buffer, size_t size) override;

private:
  void* handle;
  AutoCloseHandle autoclose;
};

#endif  // _WIN32

417
}  // namespace kj
418

419
#endif  // KJ_IO_H_