IFile

Description

interface Tinman.Core.IO.Files.IFile

Derived from: IDisposableGeneric<IFile>
IFileOps
IFlushable
ICanReadWrite
IPathInfo
Extended by: FileBase ^abstract

Base interface for classes that represent persistent binary objects (i.e. files) with random-access semantics.

Public / Methods

Commit

[ThreadSafe]
public method Commit → (2)

flush ^opt : bool = false: Perform a flush after committing all pending file modifications (see remarks)? An implementation may decide to perform a flush, even if this parameter is false, for example to maintain a limit on the size of its modification buffer.
callback ^opt : CommitDelegate = null: Optional callback to use during the commit. The callback may perform additional actions before the commit happens, for example flushing internal memory buffers. Also, the callback may cancel the commit. If null, the commit will never be cancelled.
returns → int32: The action that has been performed:
0 : no action has been performed (not supported / no changes / cancelled),
1 : all pending file modifications have been committed,
2 : same as 1, followed by a flush.

Commits all pending file modifications as an atomic update if CanCommit returns true or returns silently without performing any action otherwise.

A file may support a mechanism for ensuring file integrity, where file modifications are performed as usual and additional calls to Commit are made to group these modifications into a sequence of atomic updates:

Creation   Modifications
>__________M___M_________M___M_____M_M M_M___M__M__M__
                   C            C          C         C
                   Commits
          [--U--]       [--U--]   [---U---] [---U---]
          Atomic updates

Atomic updates are performed sequentially and each atomic update is either applied fully or not at all. In the case that a file cannot be closed properly (for example, the application crashes or the system malfunctions), all atomic updates that have not been included in a prior flush may be lost.

file.Flush();       // #1
...
file.Commit(true);  // #2
...
file.Commit(false); // #3

Calling IFlushable.Flush (see #1) will implicitly call Commit with flush set to true and is thus equivalent to calling only Commit with flush (see #2). Committing without flush (see #3) is more efficient, but the atomic updates can still be lost (but not corrupted) if a subsequent flush fails.

IOException: If an I/O error has occurred.

See also: IFile.CanCommit

GetLength

[ThreadSafe]
public method GetLength → ()

returns → int64: The current length, in bytes.

Returns the current length of this file.

IOException: If an I/O error has occurred.

GetTimestamp

[ThreadSafe]
public method GetTimestamp → ()

returns → int64: The timestamp value (see LicenceUtil.SystemTime).

Returns the timestamp of the last file modification.

If SetTimestamp has been called, this method will return the provided timestamp value. Otherwise, the method will fetch the timestamp from the underlying filesystem each time is it called.

IOException: If an I/O error has occurred.

Read

[ThreadSafe]
public method Read → (4)

offset ⁱⁿ : int64: [>=0]
Offset of first byte to read from file.
buffer ⁱⁿ : ByteBuffer: [not-null]
The output buffer. The ByteBuffer object will not be modified by this method. The current buffer position (see ByteBuffer.Position) will be queried iff bufferOffset ^opt is -1. The current buffer limit will be queried iff count ^opt is -1.
bufferOffset ^opt : int32 = -1: [>=-1]
Offset into output buffer ⁱⁿ. If set to -1, the current buffer position (see ByteBuffer.Position) will be used.
count ^opt : int32 = -1: [>=-1]
Total number of bytes to read. If set to -1, the remaining buffer bytes (see ByteBuffer.Remaining) will be used.
returns → int32: The actual number of read bytes.

Reads a chunk of bytes from the file.

The actual number of read bytes may be lower than count ^opt when reading over the end of the file. The maximum number of bytes that can be read with a single call is 2^31-1.

IOException: If an I/O error has occurred.

ReadAll

[ThreadSafe]
public method ReadAll → (4)

offset ⁱⁿ : int64: [>=0]
Offset of first byte to read from file.
buffer ⁱⁿ : ByteBuffer: [not-null]
The output buffer. The ByteBuffer object will not be modified by this method.
bufferOffset ^opt : int32 = -1: [>=-1]
Offset into output buffer ⁱⁿ. If set to -1, the current buffer position (see ByteBuffer.Position) will be used.
count ^opt : int32 = -1: [>=-1]
Total number of bytes to read. If set to -1, the remaining buffer bytes (see ByteBuffer.Remaining) will be used.

Reads a chunk of bytes from the file.

The maximum number of bytes that can be read with a single call is 2^31-1.

IOException: If an I/O error has occurred.

SetLength

[ThreadSafe]
public method SetLength → (1)

value ⁱⁿ : int64: [>=0]
The new length, in bytes.

Sets the length of this file.

Setting the length of a file may cause additional management overhead by the OS and should only be done when absolutely necessary.

IOException: If an I/O error has occurred.

SetTimestamp

[ThreadSafe]
public method SetTimestamp → (1)

timestamp ⁱⁿ : int64: The timestamp value (see LicenceUtil.SystemTime).

Sets the timestamp of the last file modification.

Once called, the GetTimestamp will return timestamp ⁱⁿ. The new timestamp may not become apparent to the underlying filesystem immediately, but it will when this file is disposed, at the latest.

IOException: If an I/O error has occurred.

Write

[ThreadSafe]
public method Write → (4)

offset ⁱⁿ : int64: [>=0]
Offset of first byte to read from file.
buffer ⁱⁿ : ByteBuffer: [not-null]
The input buffer. The ByteBuffer object will not be modified by this method.
bufferOffset ^opt : int32 = -1: [>=-1]
Offset into output buffer ⁱⁿ. If set to -1, the current buffer position (see ByteBuffer.Position) will be used.
count ^opt : int32 = -1: [>=-1]
Total number of bytes to read. If set to -1, the remaining buffer bytes (see ByteBuffer.Remaining) will be used.

Writes a chunk of bytes to the file.

The maximum number of bytes that can be written with a single call is 2^31-1. Writing past the end of the file will cause it to grow automatically.

IOException: If an I/O error has occurred.

Public / Attributes

CanCommit

public attribute CanCommit → (get)

value : bool: true if Commit can be used to ensure file integrity,
false if file integrity is not ensured.

Does this IFile support Commit?

IsLocal

public attribute IsLocal → (get)

value : bool: true if this file is local, false if not.

Is the data of this file present on the host machine?

IsTemporary

public attribute IsTemporary → (get)

value : bool: true if this file is a temporary one, false if it is a regular one.

Is this a temporary file?

The contents of a temporary file are no longer used when it is disposed.

IFile

Description

Public / Methods

Commit

Get​Length

Get​Timestamp

Read

Read​All

Set​Length

Set​Timestamp