buffer.h

Go to the documentation of this file.

#ifndef RUBY_IO_BUFFER_H
#define RUBY_IO_BUFFER_H
#pragma once
 
#include "ruby/ruby.h"
#include "ruby/internal/config.h"
 
RBIMPL_SYMBOL_EXPORT_BEGIN()
 
// WARNING: This entire interface is experimental and may change in the future!
#define RB_IO_BUFFER_EXPERIMENTAL 1
 
// Version 4: Buffer is the common view interface for Storage and Slice;
// allocation lifecycle operations require Storage. Version 3 introduced
// single-transfer IO semantics.
#define RUBY_IO_BUFFER_VERSION 4
 
// The `IO::Buffer` class.
RUBY_EXTERN VALUE rb_cIOBuffer;
RUBY_EXTERN VALUE rb_cIOBufferStorage;
RUBY_EXTERN VALUE rb_cIOBufferSlice;
 
// Returns non-zero for a native Storage or Slice representation. This verifies
// the native payload, rather than only Ruby inheritance from IO::Buffer.
int rb_io_buffer_p(VALUE self);
 
// Returns whether the view is read-only, including restrictions inherited
// from its current source.
int rb_io_buffer_readonly_p(VALUE self);
 
// The operating system page size.
RUBY_EXTERN size_t RUBY_IO_BUFFER_PAGE_SIZE;
 
// The alignment required for file mapping offsets.
RUBY_EXTERN size_t RUBY_IO_BUFFER_MAP_ALIGNMENT;
 
// The default buffer size, usually a (small) multiple of the page size.
// Can be overridden by the RUBY_IO_BUFFER_DEFAULT_SIZE environment variable.
RUBY_EXTERN size_t RUBY_IO_BUFFER_DEFAULT_SIZE;
 
// Represents the internal state of the buffer.
// More than one flag can be set at a time.
enum rb_io_buffer_flags {
    // The memory in the buffer is owned by someone else.
    // More specifically, it means that someone else owns the buffer and we shouldn't try to resize it.
    RB_IO_BUFFER_EXTERNAL = 1,
    // The memory in the buffer is allocated internally.
    RB_IO_BUFFER_INTERNAL = 2,
    // The memory in the buffer is mapped.
    // A non-private mapping is marked as external.
    RB_IO_BUFFER_MAPPED = 4,
 
    // A mapped buffer that is also shared.
    RB_IO_BUFFER_SHARED = 8,
 
    // The buffer mapping is private and will not impact other processes or the underlying file.
    RB_IO_BUFFER_PRIVATE = 64,
 
    // The buffer is read-only and cannot be modified.
    RB_IO_BUFFER_READONLY = 128,
 
    // The buffer is backed by a file.
    RB_IO_BUFFER_FILE = 256,
};
 
// Represents the endian of the data types.
enum rb_io_buffer_endian {
    // The least significant units are put first.
    RB_IO_BUFFER_LITTLE_ENDIAN = 4,
    RB_IO_BUFFER_BIG_ENDIAN = 8,
 
#if defined(WORDS_BIGENDIAN)
    RB_IO_BUFFER_HOST_ENDIAN = RB_IO_BUFFER_BIG_ENDIAN,
#else
    RB_IO_BUFFER_HOST_ENDIAN = RB_IO_BUFFER_LITTLE_ENDIAN,
#endif
 
    RB_IO_BUFFER_NETWORK_ENDIAN = RB_IO_BUFFER_BIG_ENDIAN
};
 
VALUE rb_io_buffer_new(void *base, size_t size, enum rb_io_buffer_flags flags);
// Create a buffer with an initial lock count of one. This is typically used
// for temporary wrappers around borrowed memory and paired with
// rb_io_buffer_free_locked.
VALUE rb_io_buffer_new_locked(void *base, size_t size, enum rb_io_buffer_flags flags);
VALUE rb_io_buffer_map(VALUE io, size_t size, rb_off_t offset, enum rb_io_buffer_flags flags);
 
// Acquire and release a reference-counted lock on the backing allocation.
// Every successful lock call must be paired with exactly one unlock call.
VALUE rb_io_buffer_lock(VALUE self);
VALUE rb_io_buffer_unlock(VALUE self);
int rb_io_buffer_try_unlock(VALUE self);
 
// Allocation lifecycle operations require Storage and reject Slice receivers.
VALUE rb_io_buffer_free(VALUE self);
// Release the buffer's only lock and immediately invalidate it. This is for
// temporary wrappers around borrowed memory. Calls rb_bug if the lock count is
// not exactly one.
VALUE rb_io_buffer_free_locked(VALUE self);
 
// Access the buffer and flags. Validates the pointers. READONLY reflects both
// the view's own restriction and its source's current permissions. If the
// returned base is NULL, the returned size is always zero.
// The pointers may not remain valid if the source buffer is manipulated.
// Consider using rb_io_buffer_lock if needed.
enum rb_io_buffer_flags rb_io_buffer_get_bytes(VALUE self, void **base, size_t *size);
void rb_io_buffer_get_bytes_for_reading(VALUE self, const void **base, size_t *size);
void rb_io_buffer_get_bytes_for_writing(VALUE self, void **base, size_t *size);
 
// Lock the backing allocation, invoke the callback with its readable bytes,
// and automatically unlock it when the callback returns or raises. The bytes
// are only valid for the duration of the callback. This protects the lifetime
// of the allocation; it does not provide synchronization for its contents.
VALUE rb_io_buffer_locked_for_reading(VALUE self, VALUE (*callback)(const void *base, size_t size, VALUE argument), VALUE argument);
 
// Lock the backing allocation, invoke the callback with its writable bytes,
// and automatically unlock it when the callback returns or raises. The bytes
// are only valid for the duration of the callback. This protects the lifetime
// of the allocation; it does not provide synchronization for its contents.
VALUE rb_io_buffer_locked_for_writing(VALUE self, VALUE (*callback)(void *base, size_t size, VALUE argument), VALUE argument);
 
VALUE rb_io_buffer_transfer(VALUE self);
void rb_io_buffer_resize(VALUE self, size_t size);
// Advance the start of a non-owning buffer or slice by the given amount.
void rb_io_buffer_advance(VALUE self, size_t amount);
void rb_io_buffer_clear(VALUE self, uint8_t value, size_t offset, size_t length);
 
// The length is the maximum transfer length. Each function performs one
// logical IO operation and may return a short result.
VALUE rb_io_buffer_read(VALUE self, VALUE io, size_t offset, size_t length);
VALUE rb_io_buffer_pread(VALUE self, VALUE io, rb_off_t from, size_t offset, size_t length);
VALUE rb_io_buffer_write(VALUE self, VALUE io, size_t offset, size_t length);
VALUE rb_io_buffer_pwrite(VALUE self, VALUE io, rb_off_t from, size_t offset, size_t length);
 
RBIMPL_SYMBOL_EXPORT_END()
 
#endif  /* RUBY_IO_BUFFER_H */