![]() |
![]() |
![]() |
![]() |
21 Memory Mapped I/O (MMAP.HHF)
The HLA Standard Library provides a set of routines for creating and manipulating memory-mapped files. Memory-mapped files are very efficient because they use the underlying operating systems' virtual memory subsystem for file I/O. When you open a memory-mapped file, the OS maps the entire file into the process' address space. Reading data from the file consists of nothing more than a memory access. Indeed, random file access is trivial in a memory mapped file system (you can treat the entire file as one huge array of characters from your software's point of view).
Although memory-mapped file access is very fast, the HLA Standard Library implementation does have a couple of limitations that make it unacceptable for some applications. First of all, as the operating system maps the file into your process' address space, memory-mapped files cannot exceed 2GBytes in size (in fact, the operating system might not even support files that large). Second, when processing existing files, you cannot extend the file's size. You may modify any data that already exists in the file, but you cannot append data to the end of the file. Third, when creating a new file, you must specify the size of the file when you first create it. You cannot open the file and then arbitrarily extend it during program execution as you can with a standard file.
Note that the memory-mapping module in the HLA Standard Library is implemented as a class. This class (mmap) defines the following public fields:
filePtr:dword;This field holds a pointer to the first byte of the file in memory. You must not access any data in the file prior to this address. When you create a mmap object (but haven't yet opened a memory mapped file), or after you close the memory-mapped file (using the close method described below), the mmap class initializes this field with NULL.
fileSize:dword;This field holds the size of the file when it is mapped into memory. The memory mapping module initializes this field with zero when you don't have a currently opened memory-mapped file.
endFilePtr:string;This field holds a pointer to the first byte beyond the end of the file in memory. You must not access any data in the file equal to or beyond this address. When you create a mmap object (but haven't yet opened a memory mapped file), or after you close the memory-mapped file (using the close method described below), the mmap class initializes this field with NULL.
The mmap class also contains several private fields. Your applications must not modify the values of these private fields. The class does provide accessor methods if you wish to test the values of these private fields.
procedure mmap.create;This procedure is the static class constructor. If you call this procedure using the class name (i.e., mmap.create(); ) then this constructor will allocate storage for a new mmap object on the heap, initialize that object, and return a pointer to the object in the ESI register. If you call this procedure via an object variable reference (e.g., mmapVar.create(); ) then this procedure will simply initialize the fields of that object.
As with all objects in HLA, you must call the mmap.create constructor before using the object. Failure to do so will cause the system to crash whenever you attempt to call any of this class' methods.
method mmap.destroy;This is the class destructor. It deinitializes the mmap object, closes any memory-mapped file left open, and deallocates the storage for the object if it was allocated on the heap. Note that you should not rely upon the destructor to close your memory-mapped files - you should always explicitly call the mmap.close method to do this.
method mmap.openNew( filename:string; maxSize:dword );This method opens a new memory-mapped file. The filename parameter specifies the name of the file on the disk. If the file already exists, this call will delete the file before opening a new file by that name. The filename string must be a valid pathname. The maxSize parameter specifies the size of the file (in bytes) that this call will create. You must specify the size of the memory-mapped file when you open it. This method updates the object's fields, including the filePtr, endFilePtr, and fileSize fields. This procedure does not return the pointer to the file in EAX, use the filePtr field to obtain the address of the mapped file object. Note that this method always opens the file for reading and writing.
method mmap.open( filename:string; Access:dword );This method maps an existing file into the process' address space. The filename parameter is a string specifying the pathname of the file to open. The Access parameter is either fileio.r or fileio.rw and specifies whether you're opening the file as a read-only or read/write object. This call maps the entire file into the process' address space (assuming the file is small enough to fit into the address space, of course). This method call initializes the filePtr, endFilePtr, and fileSize fields of the object as appropriate for the file.
method mmap.close;This method unmaps the file and closes it. It also resets the object's fields to their default values (e.g., filePtr=NULL, endFilePtr=NULL, and fileSize=0). You may not access data in the memory mapped file after closing the file. Note that you may re-open the same (or a different) file using mmap.open or mmap.openNew after you close a file (and you don't need to call mmap.create unless you also call mmap.destroy after calling mmap.close).
method mmap.getFileName;This is an accessor function that returns the filename string (pointer) in the EAX register. The program must not modify this string in any way.
method mmap.getOpen;This is an accessor function that returns a boolean value in AL: false if the file is not currently open, true if there is a file mapped into the process' address space. This field is only valid after you call mmap.create.
method mmap.getMalloc;This is an accessor function that returns true if the object is allocated dynamically on the heap, it returns false if the object is a static or automatic variable.
![]() |
![]() |
![]() |
![]() |
![]() |