/* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
parcel Lucy;
/** Read index files.
*
* InStream objects are the primary interface for reading from index files.
* They are high-level (relatively speaking), media-agnostic wrappers
* around low-level, media-specific FileHandle objects.
*
* InStreams provide a number of routines for safely decoding common constructs
* such as big-endian or compressed integers; for the most part, these
* routines throw exceptions rather than require manual checking of return
* values for error conditions.
*
* Multiple InStream objects often share the same underlying FileHandle; this
* practice is safe because InStreams do not modify or rely upon the file
* position or other state within the FileHandle.
*/
class Lucy::Store::InStream inherits Lucy::Object::Obj {
int64_t offset;
int64_t len;
char *buf;
char *limit;
CharBuf *filename;
FileHandle *file_handle;
FileWindow *window;
inert incremented nullable InStream*
open(Obj *file);
/** Return a new InStream, or set Err_error and return NULL on failure.
*
* @param file A FileHandle, a file path, or a RAMFile.
*/
inert nullable InStream*
do_open(InStream *self, Obj *file);
/** Clone the instream, but specify a new offset, length, and possibly
* filename. Initial file position will be set to the top of the file
* (taking offset
into account).
*
* @param filename An alias filename. If NULL, the filename of the
* underlying FileHandle will be used.
* @param offset Top of the file as seen by the new InStream, in bytes
* from the top of the file as seen by the underlying FileHandle.
* @param len Length of the file as seen by the new InStream.
*/
incremented InStream*
Reopen(InStream *self, const CharBuf *filename = NULL, int64_t offset,
int64_t len);
/** Clone the InStream. Clones share the same underlying FileHandle and
* start at the current file position, but are able to seek and read
* independently.
*/
public incremented InStream*
Clone(InStream *self);
/** Decrement the number of streams using the underlying FileHandle. When
* the number drops to zero, possibly release system resources.
*/
void
Close(InStream *self);
public void
Destroy(InStream *self);
/** Seek to target
.
*/
final void
Seek(InStream *self, int64_t target);
/** Return the current file position.
*/
final int64_t
Tell(InStream *self);
/** Return the length of the "file" in bytes.
*/
final int64_t
Length(InStream *self);
/** Fill the InStream's buffer, letting the FileHandle decide how many bytes
* of data to fill it with.
*/
void
Refill(InStream *self);
/** Pour an exact number of bytes into the InStream's buffer.
*/
void
Fill(InStream *self, int64_t amount);
/** Get the InStream's buffer. Check to see whether request
* bytes are already in the buffer. If not, fill the buffer with either
* request
bytes or the number of bytes remaining before EOF,
* whichever is smaller.
*
* @param request Advisory byte size request.
* @return Pointer to the InStream's internal buffer.
*/
final char*
Buf(InStream *self, size_t request);
/** Set the buf to a new value, checking for overrun. The idiom is for
* the caller to call Buf(), use no more bytes than requested, then use
* Advance_Buf() to update the InStream object.
*/
final void
Advance_Buf(InStream *self, char *buf);
/** Read len
bytes from the InStream into buf
.
*/
final void
Read_Bytes(InStream *self, char *buf, size_t len);
/** Read a signed 8-bit integer.
*/
final int8_t
Read_I8(InStream *self);
/** Read an unsigned 8-bit integer.
*/
final uint8_t
Read_U8(InStream *self);
/** Read a signed 32-bit integer.
*/
final int32_t
Read_I32(InStream *self);
/** Read an unsigned 32-bit integer.
*/
final uint32_t
Read_U32(InStream *self);
/** Read a signed 64-bit integer.
*/
final int64_t
Read_I64(InStream *self);
/** Read an unsigned 64-bit integer.
*/
final uint64_t
Read_U64(InStream *self);
/** Read an IEEE 764 32-bit floating point number.
*/
final float
Read_F32(InStream *self);
/** Read an IEEE 764 64-bit floating point number.
*/
final double
Read_F64(InStream *self);
/** Read in a compressed 32-bit unsigned integer.
*/
uint32_t
Read_C32(InStream *self);
/** Read a 64-bit integer, using the same encoding as a C32 but occupying
* as many as 10 bytes.
*/
final uint64_t
Read_C64(InStream *self);
/** Read the bytes for a C32/C64 into buf
. Return the number
* of bytes read. The caller must ensure that sufficient space exists in
* buf
(worst case is 10 bytes).
*/
final int
Read_Raw_C64(InStream *self, char *buf);
/** Accessor for filename member.
*/
CharBuf*
Get_Filename(InStream *self);
}