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 a simple-stream which has :mapped t specified to the operator (like to open) which creates the stream. Recall that a simple stream is created when the :element-type is not specified (see the beginning of streams.htm). 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.

This feature was made available in a patch. 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. The mapping is removed when cl:close is called on the stream.

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
• 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. For offset the system is likely to require a page alignment; the mapping may fail if the offset is not some multiple of a page size, typically 4096. For length page alignment may be needed here as well but that is less likely. Often the length argument is more lax, because the system simply rounds that argument up to the next page boundary. If the length is not page aligned, however, it would be dangerous to use any memory between the length and the page boundary.

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

Copyright (c) 1998-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.1 page.
Created 2010.1.21.