mmap (version 0.5-5)

mmap: Map And Unmap Pages of Memory

Description

Wrapper to POSIX compliant mmap system calls.

Usage

mmap(file, mode = int32(), 
     extractFUN=NULL, replaceFUN=NULL,
     prot=mmapFlags("PROT_READ","PROT_WRITE"),
     flags=mmapFlags("MAP_SHARED"),
     len, off=0L,
     ...)
munmap(x)
as.mmap(x, mode, file, ...)
is.mmap(x)
extractFUN(x)
replaceFUN(x)
extractFUN(x) <- value
replaceFUN(x) <- value

Arguments

file

name of file holding data to be mapped into memory

mode

mode of data on disk. Use one of char() (char <-> Rraw), int8() (char <-> Rinteger), uint8() (unsigned char <-> Rinteger), int16() (short <-> Rinteger), uint16() (unsigne

extractFUN

A function to convert the raw/integer/double values returned by subsetting into a complex R class. If no change is needed, set to NULL (default).

replaceFUN

A function to convert the R classes to underlying C types for storage.

prot

access permission to data being mapped. Set via bitwise OR with mmapFlags to one or more of PROT_READ: Data can be read, PROT_WRITE: Data can be written, PROT_EXEC: Data can be executed,

flags

additional flags to mmap. Set via bitwise OR with mmapFlags to one or more of MAP_SHARED: Changes are shared (default), MAP_PRIVATE: Changes are private, MAP_FIXED: Interpret

len

length in bytes of mapping from offset. (EXPERT USE ONLY)

off

offset in bytes to start mapping. This must be a multiple of the system pagesize. No checking is currently done, nor is there any mmap provision to find pagesize automatically. (EXPERT USE ONLY)

...

unused

x

an object of class mmap

value

a function to apply upon extraction or replacement.

Value

• The mmap and as.mmap call returns an object of class mmap containing the fields: [object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object]

Details

The general semantics of the R function map to the underlying POSIX C function call. The notable exception is the use of file in place of void *addr and int fildes. Additionally len and off arguments are made available to the R level call, though require special care based on the system's mmap and are advised for expert use only.

as.mmap allows for in-memory objects to be converted to mmapped version on-disk. The files are stored in the location specified by file. Passing an object that has an appropriate as.mmap method will allow Robjects to be automatically created as memory-mapped object. Additional methods may be defined to support complex data objects.

All mode types are defined for single-column atomic data, with the exception of structs. Multiple column objects are not explicitely supported, instead a mapping should be made for each column of the original object. Future versions will likely abstract this to allow for single columns per file, but the resultant mmap object in Rwill hide the underlying seperation.

Using struct as the mode will organize the binary data on-disk (or read data organized on disk) in a row-major orientation. This is similar to how a row database would be oriented, and will provide faster access to data that is typically viewed together. See help(struct) for examples of semantics as well as performance.

References

mmap: http://www.opengroup.org/onlinepubs/000095399/functions/mmap.html

See Also

See Also as mmapFlags,

Examples

# create a binary file and map into 'ints' object
# Note that we are creating a file of 1 byte integers,
# and that the conversion is handled transparently
tmp <- tempfile()
ints <- as.mmap(1:100L, mode=int8(), file=tmp)

ints[1]
ints[]
ints[22]
ints[21:23] <- c(0,0,0)
ints[]  # changes are now on disk
munmap(ints)

# store Dates as natural-size 'int' on disk
writeBin(as.integer(Sys.Date()+1:10), tmp)
DATE <- mmap(tmp,extractFUN=function(x) structure(x,class="Date"))
DATE[]
munmap(DATE)

# store 2 decimal numeric as 'int' on disk, and convert on extraction
num <- mmap(tmp,extractFUN=function(x) x/100)
num[]
munmap(num)

unlink(tmp)