NAME

TUI::Manual::09 - Streams and Persistence in TUI::Vision

STREAMS AND PERSISTENCE

Turbo Vision uses streams to separate the persistent representation of an object from its in-memory representation. TUI::Vision follows the same model: persistent framework objects describe their state through write and read, while TStream provides the sequential transport used by these methods.

This distinction is important for object structures such as views, groups and windows. Persistence does not merely copy their Perl data structures. During restoration, the framework rebuilds the relationships required by the TUI::Vision object model.

Why Streams Exist

A persistent object often contains more than independent scalar values. Objects can contain other objects, refer to objects owned elsewhere in the view hierarchy, and share references with other parts of the object graph.

Serializing the Perl representation directly would make the persistence format depend on implementation details of the object. It would also bypass the reconstruction performed by the object's read method.

TStream therefore provides a small sequential interface. An object writes its persistent state in a defined order:

sub write {
    my ( $self, $stream ) = @_;

    $stream->put( $self->{first} );
    $stream->put( $self->{second} );

    return;
}

The corresponding read method consumes the values in the same order:

sub read {
    my ( $self, $stream ) = @_;

    $self->{first}  = $stream->get();
    $self->{second} = $stream->get();

    return $self;
}

The object's write and read implementations therefore define the persistent state. The internal Perl representation does not by itself define the persistence format.

Streamable Objects

Objects that participate in object streaming perform the TStreamable role.

A TStreamable class provides two operations:

  • write

    Writes the persistent state of the object to a TStream.

  • read

    Restores the persistent state of the object from a stream.

TStream recognizes objects performing this role when they are passed to put. Ordinary values retain normal value semantics, while streamable objects participate in object identity tracking.

This corresponds to the distinction made by the original Turbo Vision object streaming system between ordinary streamed values and streamable objects.

Stream Registration

Persistence must distinguish between an object's contents and its identity.

Consider an object referenced twice:

$window->{frame} ---.
                    |
                    +----> frame object
                    |
subview ------------'

Writing the frame twice must not cause two independent frame objects to appear after restoration.

When TStream encounters a TStreamable object for the first time, it records the object's identity together with its persistent representation. If the same object is encountered again, the stream records a reference to the previously written object instead of another independent representation.

On reading, the first occurrence reconstructs the object and associates it with the recorded identity. Later references resolve to that reconstructed object.

The identifiers and registration structures used to implement this behavior are internal to the stream implementation. Applications should rely only on the resulting identity semantics.

Object Graphs

Object registration allows the restored TUI::Vision object graph to preserve shared references.

For example, a window frame can be both a field of a window and a member of the window's subview structure. These are not two equivalent frames. They are two references to the same frame object.

After persistence and restoration, the required relationship is therefore:

restored window->{frame} ---.
                            |
                            +----> restored frame
                            |
restored subview -----------'

rather than two independently reconstructed objects.

This is especially important for TUI::Vision structures. Relationships among groups, views and windows are reconstructed according to their read implementations. The stream preserves object identity while those methods rebuild the framework-specific structure.

Consequently, persistence should be understood as reconstruction of the TUI::Vision object graph, not as a direct copy of the complete in-memory Perl reference graph.

Resource Files

The stream abstraction also provides the foundation for persistent resources in the TUI::Vision architecture.

Resource storage builds on the same general principles described in this chapter: objects define their persistent state, streams transport that state, and shared streamable objects retain their identity.

Resource-specific interfaces are documented by the modules that provide them.

Conclusion

TUI::Vision separates persistence into three responsibilities:

  • Persistent objects define their state through write and read.

  • TStreamable identifies objects that participate in object streaming.

  • TStream transports values and preserves the identity of shared streamable objects while the TUI::Vision object graph is reconstructed.

This keeps persistence independent of the incidental Perl representation of framework objects while preserving the relationships required by the TUI::Vision object model.

next chapter.