AddressSpace library v1.0 beta

mmap
Class AddressSpace

java.lang.Object
  |
  +--mmap.AddressSpace

public class AddressSpace
extends java.lang.Object

This class represents a virtual address space.
I decided to develop this module to make it possible to have a lot of data available and memorized in a persistent way.
Structured files are very performing if tailored for a specific application but are difficult to manage and an hardly reusable code resource.
A better solution is a virtual memory implementation.

Every instance is connected to a data file (extension .asd) and to an index file (extension .asi). The former is responsible for containing the data, the latter contains informations relatives to data storing and pages organization.
Access to the data file is achieved using read and write call on the swapping space object. The swap space is responsible for allocating new pages and retrieving old ones from the data file.
Data (both index and real data) are stored in 4 Kbytes pages. The index file is made up of a first page called master index page, where are stored integer referring to positions of other pages inside the index file following the master index, those pages are referred as secondary index pages. Inside a secondary index page integers are stored to locate a data page inside the data file.
The addressing is made by 32 bit words, where the first 20 bits are relative to the page, the latest 12 are relative to the byte inside the page.
The first ten bits of the address are used inside the master index page to locate the position of the secondary index page, the following ten bits are used to locate the data page inside the data file.
By convention a number 0 means that the page is not (yet) present in the addressing space.
Pages are cached by the application, when the user create the instance the number of pages to remain in central memory can be provided.
Cache can be modified dynamically during operations and is digested in a Least Recently Used algorithm.
Inside the swapping space the caches are connected to synching threads that are responsible to keep memory and disk images synched on a timed basis.

BEWARE

no tools for data integrity are provided
they will in a future release.

Version:
1.0 June 05 2000
Author:
Dario Maggiorini (dario@dsi.unimi.it)

Constructor Summary
AddressSpace(java.lang.String filename)
          Connect to an already existing address space.
AddressSpace(java.lang.String filename, int cacheSizeInKB)
          Connect to an already existing address space.
 
Method Summary
 void close()
          Close the address space.
static void createSpace(java.lang.String spaceName)
          Create a new empty swap space.
static void createSpace(java.lang.String spaceName, java.lang.String informations)
          Create a new empty swap space.
 void dumpCache(java.lang.String fileName)
          Create a file image of the data cache in a human-readable format.
 byte read(int offset)
          Read a byte value from the address space.
 int read(int offset, byte[] buffer)
          Read a byte array from the address space.
 int read(int offset, byte[] buffer, int len)
          Read a byte array from the address space until a certain amount of data is transferred.
 int read(int offset, byte[] buffer, int len, int boffset)
          Read a byte array from the address space starting from an offset until a certain amount of data is transferred.
 int readInt(int offset)
          Read an int value from the address space.
 long readLong(int offset)
          Read a long int value from the address space.
 short readShort(int offset)
          Read a short int value from the address space.
 void setCache(int sizeInBytes)
          Set the cache size.
 void setTimer(int newTimer)
          Set timing for synchers.
 void shrink()
          Shrink the data file purging all the empty pages.
 void sync()
          Synchronize memory and disk images of cached pages.
 void trashPage(int location, int id)
          Destroy a page.
 int write(int offset, byte v)
          Write a byte value inside the address space.
 int write(int offset, byte[] buffer)
          Write a byte array inside the address space.
 int write(int offset, byte[] buffer, int len)
          Write a byte array inside the address space until a certain amount of data is transferred.
 int write(int offset, byte[] buffer, int len, int boffset)
          Write a byte array inside the address space starting from an offset until a certain amount of data is transferred.
 int writeInt(int offset, int value)
          Write an int value inside the address space.
 int writeLong(int offset, long value)
          Write a long int value inside the address space.
 int writeShort(int offset, short value)
          Write a short int value inside the address space.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

AddressSpace

public AddressSpace(java.lang.String filename,
                    int cacheSizeInKB)
             throws java.io.IOException
Connect to an already existing address space.
The address space has to be created before instantiating (and connecting).
Parameters:
filename - the name of the address space file.
cacheSizeInKB - the size of the cache.
See Also:
createSpace

AddressSpace

public AddressSpace(java.lang.String filename)
             throws java.io.IOException
Connect to an already existing address space.
The address space has to be created before instantiating (and connecting).
Parameters:
filename - the name of the address space file.
See Also:
createSpace
Method Detail

close

public void close()
           throws java.lang.InterruptedException,
                  java.io.IOException
Close the address space.
The address space memory image is synched to disk, all descriptors are closed and all tables are wiped out.

trashPage

public void trashPage(int location,
                      int id)
               throws java.io.IOException
Destroy a page.
The page is no longer needed in the address space.
This can happen when a page that has only zeros as data jump out of the cache or is synched.
Zero data is not useful, so the page and is place inside the data file are freed.
No data is physically removed (the place will be reused), only a zero is inserted inside the secondary index page referring to this data page.

This function is NOT intended to be used by a final user.
Will be removed in a future release.

Parameters:
location - the location to mark as free inside the data file.
id - the id of the page to be trashed.

sync

public void sync()
          throws java.io.IOException
Synchronize memory and disk images of cached pages.

shrink

public void shrink()
            throws java.io.IOException
Shrink the data file purging all the empty pages.
Informations inside the data page are moved to make the free pages accumulate to the end of the data file.
The file is then truncated to the required size.
Returns:
IOException if data or index file can't be written.

setTimer

public void setTimer(int newTimer)
              throws java.lang.InterruptedException
Set timing for synchers.
The time interval between calls of the synchers is set to the parameter value in seconds.
Synching threads are destroyed and new ones are created with the new timing value.
Parameters:
newTimer - seconds that should pass between syncs.

setCache

public void setCache(int sizeInBytes)
              throws java.io.IOException
Set the cache size.
The cache size is set to the provided value in byte.
Parameters:
sizeInBytes - the new cache size.

dumpCache

public void dumpCache(java.lang.String fileName)
Create a file image of the data cache in a human-readable format.
This is intended for debugging purposes.
Parameters:
fileName - the file name where dump the cache.

read

public byte read(int offset)
          throws java.io.IOException
Read a byte value from the address space.
Parameters:
offset - the address where to read the byte from.
Returns:
the byte readed.

write

public int write(int offset,
                 byte v)
          throws java.io.IOException
Write a byte value inside the address space.
Parameters:
offset - the address where to write the byte.
v - the value to write
Returns:
the number of bytes actually written to the address space.

read

public int read(int offset,
                byte[] buffer)
         throws java.io.IOException
Read a byte array from the address space.
Parameters:
offset - the address where to read the array from.
buffer - the buffer where the data will be stored.
Returns:
number of bytes actually readed from the address space.

write

public int write(int offset,
                 byte[] buffer)
          throws java.io.IOException
Write a byte array inside the address space.
Parameters:
offset - the address where to write the bytes.
buffer - the buffer containing the data to transfer.
Returns:
the number of bytes actually written to the address space.

read

public int read(int offset,
                byte[] buffer,
                int len)
         throws java.io.IOException
Read a byte array from the address space until a certain amount of data is transferred.
Parameters:
offset - the address where to read the array from.
buffer - the buffer where the data will be stored.
len - the quantity of data to transfer.
Returns:
number of bytes actually readed from the address space.

write

public int write(int offset,
                 byte[] buffer,
                 int len)
          throws java.io.IOException
Write a byte array inside the address space until a certain amount of data is transferred.
Parameters:
offset - the address where to write the bytes.
buffer - the buffer containing the data to transfer.
len - the quantity of data to transfer.
Returns:
the number of bytes actually written to the address space.

read

public int read(int offset,
                byte[] buffer,
                int len,
                int boffset)
         throws java.io.IOException
Read a byte array from the address space starting from an offset until a certain amount of data is transferred.
Parameters:
offset - the address where to read the array from.
buffer - the buffer where the data will be stored.
len - the quantity of data to transfer.
boffset - the offset inside the buffer.
Returns:
number of bytes actually readed from the address space.

write

public int write(int offset,
                 byte[] buffer,
                 int len,
                 int boffset)
          throws java.io.IOException
Write a byte array inside the address space starting from an offset until a certain amount of data is transferred.
Parameters:
offset - the address where to write the bytes.
buffer - the buffer containing the data to transfer.
len - the quantity of data to transfer.
boffset - the offset inside the buffer.
Returns:
the number of bytes actually written to the address space.

readShort

public short readShort(int offset)
                throws NotAlignedPointer,
                       java.io.IOException
Read a short int value from the address space.
Parameters:
offset - the address where to read the data from.
Returns:
the short readed.

writeShort

public int writeShort(int offset,
                      short value)
               throws NotAlignedPointer,
                      java.io.IOException
Write a short int value inside the address space.
Parameters:
offset - the address where to write the data.
value - the value to write
Returns:
the number of bytes actually written to the address space.

readInt

public int readInt(int offset)
            throws NotAlignedPointer,
                   java.io.IOException
Read an int value from the address space.
Parameters:
offset - the address where to read the data from.
Returns:
the short readed.

writeInt

public int writeInt(int offset,
                    int value)
             throws NotAlignedPointer,
                    java.io.IOException
Write an int value inside the address space.
Parameters:
offset - the address where to write the data.
value - the value to write
Returns:
the number of bytes actually written to the address space.

readLong

public long readLong(int offset)
              throws NotAlignedPointer,
                     java.io.IOException
Read a long int value from the address space.
Parameters:
offset - the address where to read the data from.
Returns:
the short readed.

writeLong

public int writeLong(int offset,
                     long value)
              throws NotAlignedPointer,
                     java.io.IOException
Write a long int value inside the address space.
Parameters:
offset - the address where to write the data.
value - the value to write
Returns:
the number of bytes actually written to the address space.

createSpace

public static void createSpace(java.lang.String spaceName)
Create a new empty swap space.
Parameters:
spaceName - the base filename to use for the swap space.

createSpace

public static void createSpace(java.lang.String spaceName,
                               java.lang.String informations)
Create a new empty swap space.
A string of informations can be added to the header of the swap.
Since the header size is limited to 1024 bytes this string can be truncated depending of the other header informations.
Parameters:
spaceName - the base filename to use for the swap space.

Help is irrilevant
You will be assimilated!

v1.0 beta by Dario Maggiorini