tcl-mmap(n)tcl-mmap(n)NAMEtcl-mmap - POSIX Message Queues for Tcl
SYNOPSIS
package require mmap
mmap ?-shared? ?-length bytes? ?-offset bytes? channelId
DESCRIPTION
This extension provides a Tcl interface to the mmap(2) POSIX system
call and associate functions: msync(2) and munmap(2).
In POSIX Operating Systems, the 'mmap' system call maps a regular file
to a memory region. Any operation (read or write) performed on the mem‐
ory region is reflected back to the mmapped file. The primary advantage
of 'mmap' over regular file access is speed, since memory operations
are generally faster and make better use of virtual memory. In fact,
the speed-up can be as much as 100% [1].
The functionality of 'mmap' is exported from this extension in the form
of a new Tcl channel type, named "mmap". A memory mapping is estab‐
lished with the 'mmap' command. Following 'mmap' execution, access to
the memory mapped file is done via the standard Tcl commands:
puts/gets/seek/flush/close/fconfigure, only that this time these com‐
mands operate on memory, rather than on a file.
The "mmap" channel type is by nature non-blocking, and by default it is
in non-buffering mode. It is absolutely essential that they remain
always in this mode.
The 'mmap' command accepts the following parameters:
-shared With this flag, memory changes propagate back to the file.
Without this flag changes remain in memory only. This flag when used to
map /dev/zero allows for shared memory of the same area between related
processes. Default is not shared.
-length The number of bytes of the target file to map into memory. If
not set, the whole file is mapped.
-offset File offset to start mapping from.
channelId An open Tcl file channel that points to the file to be
mapped.
Returns: A newly created channelId for the requested memory map.
The access pattern of channelId is transfered to the memory map. In
other words, if the file is opened "r+", then the memory map will also
accept read and write operations; if the file is opened "r" then only
read operations are permitted. A write-only file (either "w" or "a") is
not acceptable. After 'mmap' is executed, the associated file can be
closed with no effect to the file-memory mapping.
The mapping is released either when the process terminates or the asso‐
ciated file descriptor is closed. Synchronization between memory and
file is enforced with every write. However notice that Tcl might buffer
data, and hence the file might not remain synchronized with the memory
all the time. Use 'flush' or 'fconfigure' to set the channel buffering
to "none" to guarantee synchronization at all times.
Note that writing to the memory of the mmaped file cannot extent the
file itself. Writes at the end of the file automatically loop around
the start of it. Reads, on the other hand, that reach end of file,
return EOF.
Some possible usages for this extension are:
1. To memory map files for improved access efficiency (read & write).
2. Shared memory between related processes (Tcl interpreters) by memory
mapping the same area of /dev/zero.
3. Easily and intuitively implement log files with the following prop‐
erties:
a. The log file has fixed pre-determined size. Thus a runaway
process that continuous logs messages cannot cause system breakdown due
to exhaustion of available disk space.
b. The log file always retain the most recent messages that fit
within its size.
c. The log file is persistent in the sence that all log operations
are reflected directly to the file.
d. The log file is cyclic. When a write would go past the end of
the file, the file seek position is initialized to zero, and write con‐
tinues from the start of the file. (File reads on the other hand don't
loop).
EXAMPLE
package require mmap
# Open a specific region of the file
set fd [open /var/log/messages r]
set mp [mmap -length 300 -offset 4096 $fd]
close $fd
# Read that region
puts Gets:
for {set i 0} {$i < 10} {incr i} {
gets $mp line
puts $line
}
close $mp
# Open for read/write
set fd [open /var/log/messages r+]
set mp [mmap -shared -length 30 $fd]
close $fd
# Use seek to move around the memory mapped file
seek $mp 1
puts -nonewline $mp alex ;# Will overwrite contents
# Force synchronization
flush $mp
# Read the whole file
puts Read:
seek $mp 0
puts [read $mp]
# EOF works as expected
puts [eof $mp]
# Release reserved memory & synchronize
close $mp
AUTHOR
Alexandros Stergiakis sterg@kth.se
COPYRIGHT
Copyright (C) 2008 Alexandros Stergiakis
This program is free software: you can redistribute it and/or
modify it under the terms of the GNU General Public License as
published by the Free Software Foundation, either version 3 of
the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.
Tcl-Extensions 1.0 tcl-mmap(n)
