mapped-file-simple-stream

This simple-stream subclass is a subclass of both file-simple-stream and direct-simple-stream. Similar to file-simple-stream but opening a mapped file allows for much faster access to the file, with much less kernel overhead. Note: most operating systems do not allow the automatic extension of mapped files, so this class does not allow the extending operation either. Writes beyond the end of the file may cause an error.

A mapped file must be opened with :mapped t specified to open. The direction argument to open should be :input or :io. The file should have permissions consistent with the value specified to direction: if :input is specified, the file must be readable; if :io is specified, it must be both readable and writable.

The handle of a mapped file can be released at stream creation time if the option :release-handle t is specified. open will then return a stream which has been mapped to a file but for which the file number (the handle) has been closed. The mapping is not removed, but the file handle is made available for use in other file stream situations.

After a mapped-file-simple-stream is opened, the excl::buffer slot contains an aligned pointer (see the section Aligned pointers in ftype.htm). This value can be used with any accessors that support aligned pointers, e.g. fslot-value-typed with an :aligned allocation.

The options when creating an instance of this class are:

• filename (required)
• direction (defaults to :input)
• if-exists
• if-does-not-exist
• external-format (defaults to :default)
• input-handle
• output-handle
• release-handle: releases the handle of a mapped file. The mapping is not removed, but the file handle is made available for use in other file stream situations.
• mapped
• length (the length of the mapping)
• offset (the number of bytes beyond the start of the file where the mapping begins)
• fn-in (another name for the input-handle, for compatibility only, do not specify both)
• fn-out (another name for the output handle, for compatibility only, do not specify both)

See device-open for a description of the input-handle, output-handle, and mapped options.

For the offset and length arguments, no attempt is made to validate their values; they are passed to the underlying mapping implementation. Generally these arguments have some alignment requirements, but the specific requirements are up to the individual operating system. The offset argument is checked for alignment to at least natural-word alignment. This ensures that the final value for the buffer slot remains an aligned pointer.

See streams.htm for general information on simple-streams in Allegro CL.

Copyright (c) 1998-2012, Franz Inc. Oakland, CA., USA. All rights reserved.
Documentation for Allegro CL version 9.0. This page was not revised from the 8.2 page.
Created 2012.5.30.