org.apfloat
Class ApfloatContext

java.lang.Object
  extended by org.apfloat.ApfloatContext
All Implemented Interfaces:
Cloneable

public class ApfloatContext
extends Object
implements Cloneable

This class encapsulates the information needed by the apfloat implementation to perform computations.

All environment related settings of an apfloat implementation are accessed through an ApfloatContext. Such settings include for example the implementation provider class, maximum memory size to be used, and the file names that are used for temporary files.

For performance reasons, access to an ApfloatContext is not synchronized. Presumably, this won't be a problem in most cases. But, if the code needs to concurrently modify and access an ApfloatContext, all access to it should be externally synchronized.

At simplest, there is just one ApfloatContext, the global apfloat context. All settings in your application are retrieved through it. The global context is created when the ApfloatContext class is loaded, and it's thus always available.

Values for the different settings in the global apfloat context are specified in the apfloat.properties file, found in the class path. Since they are loaded via a ResourceBundle named "apfloat", you can alternatively deploy a ResourceBundle class named "apfloat" in your class path to avoid having a .properties file, or to define properties dynamically at run time.

The different settings that can be specified in the apfloat.properties file are as follows:

An example apfloat.properties file could contain the following:

 builderFactory=org.apfloat.internal.IntBuilderFactory
 defaultRadix=10
 maxMemoryBlockSize=50331648
 cacheL1Size=8192
 cacheL2Size=262144
 cacheBurst=32
 memoryTreshold=65536
 blockSize=65536
 numberOfProcessors=1
 filePath=
 fileInitialValue=0
 fileSuffix=.ap
 cleanupAtExit=true
 
The total memory size and the number of processors are detected automatically, as reported by the Java runtime, if they are not specified in the configuration bundle.

If you need to create a complex multithreaded application that performs apfloat calculations in parallel using multiple threads, you may need to change the ApfloatContext settings for the different working threads.

If thread-specific apfloat contexts are not specified, all threads will use the global context. To set a thread specific context, you would typically create a clone() of the global (or other parent) context, and then set that context to the thread using setThreadContext(ApfloatContext,Thread). Note that if you do not create a clone of the context, the same context will still be used, since it's passed by reference.

Typically you may need to set the following properties for each thread:

The other settings are generally global and do not typically need to be set differently for each thread.

Unfortunately, Java doesn't allow detecting automatically many of the settings, such as cache sizes. Also, for optimal performance, it would usually be desirable to set each thread's processor affinity (which physical processor runs which thread), which is also not possible. If these features are added to the Java platform in the future, they may be added to the ApfloatContext API as well.

Version:
1.4.1
Author:
Mikko Tommila

Field Summary
static String BLOCK_SIZE
          Property name for specifying the I/O block size.
static String BUILDER_FACTORY
          Property name for specifying the apfloat builder factory class.
static String CACHE_BURST
          Property name for specifying the level 1 cache burst size.
static String CACHE_L1_SIZE
          Property name for specifying the level 1 cache size.
static String CACHE_L2_SIZE
          Property name for specifying the level 2 cache size.
static String CLEANUP_AT_EXIT
          Property name for specifying if clean-up should be done at program exit.
static String DEFAULT_RADIX
          Property name for specifying the default radix.
static String FILE_INITIAL_VALUE
          Property name for specifying the temporary file initial value.
static String FILE_PATH
          Property name for specifying the temporary file path.
static String FILE_SUFFIX
          Property name for specifying the temporary file suffix.
static String MAX_MEMORY_BLOCK_SIZE
          Property name for specifying the maximum memory block size.
static String MEMORY_TRESHOLD
          Property name for specifying the apfloat memory treshold.
static String NUMBER_OF_PROCESSORS
          Property name for specifying the number of processors available.
 
Constructor Summary
ApfloatContext(Properties properties)
          Create a new ApfloatContext using the specified properties.
 
Method Summary
static void clearThreadContexts()
          Removes all thread-specific ApfloatContexts.
 Object clone()
          Creates a copy of this object.
 Object getAttribute(String name)
          Get an arbitrary object as an attribute for this ApfloatContext.
 Enumeration<String> getAttributeNames()
          Get names of all attributes for this ApfloatContext.
 int getBlockSize()
          Get the I/O block size.
 BuilderFactory getBuilderFactory()
          Get the BuilderFactory.
 int getCacheBurst()
          Get the level 1 cache burst size.
 int getCacheL1Size()
          Get the level 1 cache size.
 int getCacheL2Size()
          Get the level 2 cache size.
 boolean getCleanupAtExit()
          Get if clean-up should be performed at the time the program exits.
static ApfloatContext getContext()
          Get the ApfloatContext for the calling thread.
static ExecutorService getDefaultExecutorService()
          Returns a new instance of a default ExecutorService.
 int getDefaultRadix()
          Get the default radix.
 ExecutorService getExecutorService()
          Get the ExecutorService.
 FilenameGenerator getFilenameGenerator()
          Get the FilenameGenerator.
static ApfloatContext getGlobalContext()
          Get the global ApfloatContext.
 long getMaxMemoryBlockSize()
          Get the maximum memory block size.
 int getMemoryTreshold()
          Get the memory treshold.
 int getNumberOfProcessors()
          Get the number of processors.
 Properties getProperties()
          Get the values of all properties as strings.
 String getProperty(String propertyName)
          Get the value of a property as string.
 Object getSharedMemoryLock()
          Get the shared memory lock object.
static ApfloatContext getThreadContext()
          Get the thread-specific ApfloatContext for the calling thread.
static ApfloatContext getThreadContext(Thread thread)
          Get the thread-specific ApfloatContext for the specified thread.
static Properties loadProperties()
          Loads properties from a properties file or resource bundle.
 Object removeAttribute(String name)
          Remove an attribute from this ApfloatContext.
static void removeThreadContext()
          Removes the thread-specific context for the current thread.
static void removeThreadContext(Thread thread)
          Removes the thread-specific context for the specified thread.
 Object setAttribute(String name, Object value)
          Set an arbitrary object as an attribute for this ApfloatContext.
 void setBlockSize(int blockSize)
          Set the efficient I/O block size in bytes for this context.
 void setBuilderFactory(BuilderFactory builderFactory)
          Set the BuilderFactory.
 void setCacheBurst(int cacheBurst)
          Set the L1 cache burst block size in bytes.
 void setCacheL1Size(int cacheL1Size)
          Set the L1 cache size in bytes.
 void setCacheL2Size(int cacheL2Size)
          Set the L2 cache size in bytes.
 void setCleanupAtExit(boolean cleanupAtExit)
          Set if clean-up should be performed at the time the program exits.
 void setDefaultRadix(int radix)
          Set the default radix.
 void setExecutorService(ExecutorService executorService)
          Set the ExecutorService.
 void setFilenameGenerator(FilenameGenerator filenameGenerator)
          Set the FilenameGenerator.
 void setMaxMemoryBlockSize(long maxMemoryBlockSize)
          Set the maximum allowed memory block size in bytes.
 void setMemoryTreshold(int memoryTreshold)
          Set the maximum size of apfloats in bytes that are stored in memory within this context.
 void setNumberOfProcessors(int numberOfProcessors)
          Set the number of processors available to calculations using this context.
 void setProperties(Properties properties)
          Set the values of all properties as strings.
 void setProperty(String propertyName, String propertyValue)
          Set the value of a property as string.
 void setSharedMemoryLock(Object lock)
          Set the shared memory lock object.
static void setThreadContext(ApfloatContext threadContext)
          Set the thread-specific ApfloatContext for the calling thread.
static void setThreadContext(ApfloatContext threadContext, Thread thread)
          Set the thread-specific ApfloatContext for the specified thread.
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

BUILDER_FACTORY

public static final String BUILDER_FACTORY
Property name for specifying the apfloat builder factory class.

See Also:
Constant Field Values

DEFAULT_RADIX

public static final String DEFAULT_RADIX
Property name for specifying the default radix.

See Also:
Constant Field Values

MAX_MEMORY_BLOCK_SIZE

public static final String MAX_MEMORY_BLOCK_SIZE
Property name for specifying the maximum memory block size.

See Also:
Constant Field Values

CACHE_L1_SIZE

public static final String CACHE_L1_SIZE
Property name for specifying the level 1 cache size.

See Also:
Constant Field Values

CACHE_L2_SIZE

public static final String CACHE_L2_SIZE
Property name for specifying the level 2 cache size.

See Also:
Constant Field Values

CACHE_BURST

public static final String CACHE_BURST
Property name for specifying the level 1 cache burst size.

See Also:
Constant Field Values

MEMORY_TRESHOLD

public static final String MEMORY_TRESHOLD
Property name for specifying the apfloat memory treshold.

See Also:
Constant Field Values

BLOCK_SIZE

public static final String BLOCK_SIZE
Property name for specifying the I/O block size.

See Also:
Constant Field Values

NUMBER_OF_PROCESSORS

public static final String NUMBER_OF_PROCESSORS
Property name for specifying the number of processors available.

See Also:
Constant Field Values

FILE_PATH

public static final String FILE_PATH
Property name for specifying the temporary file path.

See Also:
Constant Field Values

FILE_INITIAL_VALUE

public static final String FILE_INITIAL_VALUE
Property name for specifying the temporary file initial value.

See Also:
Constant Field Values

FILE_SUFFIX

public static final String FILE_SUFFIX
Property name for specifying the temporary file suffix.

See Also:
Constant Field Values

CLEANUP_AT_EXIT

public static final String CLEANUP_AT_EXIT
Property name for specifying if clean-up should be done at program exit.

See Also:
Constant Field Values
Constructor Detail

ApfloatContext

public ApfloatContext(Properties properties)
               throws ApfloatRuntimeException
Create a new ApfloatContext using the specified properties.

Parameters:
properties - The properties for the ApfloatContext.
Throws:
ApfloatRuntimeException
Method Detail

getContext

public static ApfloatContext getContext()
Get the ApfloatContext for the calling thread. If a thread-specific context has not been specified, the global context is returned.

Returns:
The ApfloatContext for the calling thread.

getGlobalContext

public static ApfloatContext getGlobalContext()
Get the global ApfloatContext.

Returns:
The global ApfloatContext.

getThreadContext

public static ApfloatContext getThreadContext()
Get the thread-specific ApfloatContext for the calling thread.

Returns:
The ApfloatContext for the calling thread, or null if one has not been specified.

getThreadContext

public static ApfloatContext getThreadContext(Thread thread)
Get the thread-specific ApfloatContext for the specified thread.

Parameters:
thread - The thread whose ApfloatContext is to be returned.
Returns:
The ApfloatContext for the specified thread, or null if one has not been specified.

setThreadContext

public static void setThreadContext(ApfloatContext threadContext)
Set the thread-specific ApfloatContext for the calling thread.

Parameters:
threadContext - The ApfloatContext for the calling thread.

setThreadContext

public static void setThreadContext(ApfloatContext threadContext,
                                    Thread thread)
Set the thread-specific ApfloatContext for the specified thread.

Parameters:
threadContext - The ApfloatContext for the specified thread.
thread - The thread whose ApfloatContext is to be set.

removeThreadContext

public static void removeThreadContext()
Removes the thread-specific context for the current thread.


removeThreadContext

public static void removeThreadContext(Thread thread)
Removes the thread-specific context for the specified thread.

Parameters:
thread - The thread whose ApfloatContext is to be removed.

clearThreadContexts

public static void clearThreadContexts()
Removes all thread-specific ApfloatContexts.


getBuilderFactory

public BuilderFactory getBuilderFactory()
Get the BuilderFactory.

Returns:
The BuilderFactory for this ApfloatContext.

setBuilderFactory

public void setBuilderFactory(BuilderFactory builderFactory)
Set the BuilderFactory.

Parameters:
builderFactory - The BuilderFactory for this ApfloatContext.

getFilenameGenerator

public FilenameGenerator getFilenameGenerator()
Get the FilenameGenerator.

Returns:
The FilenameGenerator for this ApfloatContext.

setFilenameGenerator

public void setFilenameGenerator(FilenameGenerator filenameGenerator)
Set the FilenameGenerator.

Parameters:
filenameGenerator - The FilenameGenerator for this ApfloatContext.

getDefaultRadix

public int getDefaultRadix()
Get the default radix.

Returns:
The default radix for this ApfloatContext.

setDefaultRadix

public void setDefaultRadix(int radix)
Set the default radix. The default value is 10.

Parameters:
radix - The default radix for this ApfloatContext.

getMaxMemoryBlockSize

public long getMaxMemoryBlockSize()
Get the maximum memory block size.

Returns:
The maximum memory block size.
See Also:
setMaxMemoryBlockSize(long)

setMaxMemoryBlockSize

public void setMaxMemoryBlockSize(long maxMemoryBlockSize)
Set the maximum allowed memory block size in bytes. Apfloat will allocate an array at most of this size for calculations using this context. The minimum value for this setting is 65536.

If you set the value of this parameter too low, performance will suffer greatly as data is unnecessarily paged to disk. If you set this value too high, your application can crash with an OutOfMemoryError.

The default value for this setting is 80% of the total memory available to the VM at application startup, as reported by Runtime.totalMemory(), rounded down to the nearest power of two or three times a power of two.

Parameters:
maxMemoryBlockSize - Maximum allocated memory block size in bytes.

getCacheL1Size

public int getCacheL1Size()
Get the level 1 cache size.

Returns:
The level 1 cache size.
See Also:
setCacheL1Size(int)

setCacheL1Size

public void setCacheL1Size(int cacheL1Size)
Set the L1 cache size in bytes. The minimum value for this setting is 512.

This setting has a minor performance impact on some memory intensive operations. Unless you really want to tweak the performance, it's better to not touch this setting.

The default value for this setting is 8kB.

Parameters:
cacheL1Size - The level 1 cache size in bytes.

getCacheL2Size

public int getCacheL2Size()
Get the level 2 cache size.

Returns:
The level 2 cache size.
See Also:
setCacheL2Size(int)

setCacheL2Size

public void setCacheL2Size(int cacheL2Size)
Set the L2 cache size in bytes. The minimum value for this setting is 2048. This setting has a minor performance impact on some memory intensive operations. Unless you really want to tweak the performance, it's better to not touch this setting.

The default value for this setting is 256kB.

Parameters:
cacheL2Size - The level 2 cache size in bytes.

getCacheBurst

public int getCacheBurst()
Get the level 1 cache burst size.

Returns:
The cache burst size.
See Also:
setCacheBurst(int)

setCacheBurst

public void setCacheBurst(int cacheBurst)
Set the L1 cache burst block size in bytes. This value is also known as "L1 cache line size".

Some common values are:

The processor will move at least this amount of bytes whenever data is moved between the level 1 cache and other memory (lower level cache or main memory). Note that other cache levels than L1 may have a different line size. The minimum value for this setting is 8.

This setting has a minor performance impact on some memory intensive operations. Unless you really want to tweak the performance, it's usually better to not touch this setting. Though, if you have e.g. a Pentium 4 processor, you may want to increase the value of this setting to 64 from the default value of 32.

Parameters:
cacheBurst - The number of bytes in a L1 cache line.

getMemoryTreshold

public int getMemoryTreshold()
Get the memory treshold.

Returns:
The memory treshold.
See Also:
setMemoryTreshold(int)

setMemoryTreshold

public void setMemoryTreshold(int memoryTreshold)
Set the maximum size of apfloats in bytes that are stored in memory within this context. The minimum value for this setting is 128.

If the memory treshold is too small, performance will suffer as small numbers are stored to disk, and the amount of disk I/O overhead becomes significant. On the other hand, if the memory treshold is too big, you can get an OutOfMemoryError.

The optimal value depends greatly on each application. Obviously, if you have plenty of heap space and don't create too many too big numbers you are not likely to have problems. The default value of this setting is 64kB.

Parameters:
memoryTreshold - The number of bytes that apfloats that are stored in memory will at most have within this context.

getBlockSize

public int getBlockSize()
Get the I/O block size.

Returns:
The I/O block size.
See Also:
setBlockSize(int)

setBlockSize

public void setBlockSize(int blockSize)
Set the efficient I/O block size in bytes for this context. The minimum value for this setting is 128.

If the block size is too small, the overhead of each I/O call will definetely have an adverse effect on performance. Setting the block size very big will not affect performance significantly, but can increase intermediate memory consumption a lot, possibly resulting in running out of memory with an OutOfMemoryError. A recommended minimum value is at least a few kilobytes.

In many places, data in files is accessed in reverse order, fetching blocks of this size. Probably the optimal value of this setting is roughly half of the read-ahead buffer size of you hard disk. The default value is 64kB.

Parameters:
blockSize - The I/O block size in bytes to be used in calculations using this context.

getNumberOfProcessors

public int getNumberOfProcessors()
Get the number of processors.

Returns:
The number of processors.
See Also:
setNumberOfProcessors(int)

setNumberOfProcessors

public void setNumberOfProcessors(int numberOfProcessors)
Set the number of processors available to calculations using this context. The minimum value for this setting is 1. The default is to use all processors (CPU cores) available.

Parameters:
numberOfProcessors - Number of processors available to calculations using this context.

getCleanupAtExit

public boolean getCleanupAtExit()
Get if clean-up should be performed at the time the program exits.

Returns:
true if clean-up will be done at JVM exit, or false if not.
See Also:
setCleanupAtExit(boolean)

setCleanupAtExit

public void setCleanupAtExit(boolean cleanupAtExit)
Set if clean-up should be performed at the time the program exits. The clean-up runs garbage collection and finalization to remove any remaining temporary files that may have been created. The default behavior is true.

For example unsigned applets must have this property set to false, since they do not have access to setting shutdown hooks.

Note that if this setting is ever set to true in any ApfloatContext (and never set to false subsequently in that context), then clean-up will be performed.

Parameters:
cleanupAtExit - true if clean-up should be done at JVM exit, or false if not.

getProperty

public String getProperty(String propertyName)
Get the value of a property as string. The name of the property can be any of the constants defined above.

Parameters:
propertyName - The name of the property.
Returns:
The value of the property as a String.

setProperty

public void setProperty(String propertyName,
                        String propertyValue)
                 throws ApfloatRuntimeException
Set the value of a property as string. The name of the property can be any of the constants defined above.

Parameters:
propertyName - The name of the property.
propertyValue - The value of the property as a String.
Throws:
ApfloatRuntimeException

getProperties

public Properties getProperties()
Get the values of all properties as strings. The names of the properties are all of the constants defined above.

Returns:
The properties.

getSharedMemoryLock

public Object getSharedMemoryLock()
Get the shared memory lock object. All internal functions that allocate a memory block larger than the memory treshold should synchronize the allocation and memory access on the object returned by this method.

Returns:
The object on which large memory block allocation and access should be synchronized.

setSharedMemoryLock

public void setSharedMemoryLock(Object lock)
Set the shared memory lock object. All internal functions that allocate a memory block larger than the memory treshold should synchronize the allocation and memory access on the object passed to this method.

The object is not used for anything else than synchronization, so the class of the object should really be java.lang.Object. One would typically call this method e.g. as ctx.setSharedMemoryLock(new Object()).

Parameters:
lock - The object on which large memory block allocation and access should be synchronized.

getExecutorService

public ExecutorService getExecutorService()
Get the ExecutorService. It can be used for executing operations in parallel.

By default the executor service is a thread pool that is shared by all the ApfloatContexts. The threads in the pool are daemon threads so the thread pool requires no clean-up at shutdown time.

Returns:
The ExecutorService.
Since:
1.1

setExecutorService

public void setExecutorService(ExecutorService executorService)
Set the ExecutorService.

Note that if a custom ExecutorService is used, e.g. a thread pool, it is the caller's responsibility to clean up the ExecutorService at shutdown.

Parameters:
executorService - The ExecutorService.
Since:
1.1

getAttribute

public Object getAttribute(String name)
Get an arbitrary object as an attribute for this ApfloatContext.

Parameters:
name - Name of the attribute.
Returns:
Value of the attribute or null if the attribute doesn't exist.

setAttribute

public Object setAttribute(String name,
                           Object value)
Set an arbitrary object as an attribute for this ApfloatContext.

Parameters:
name - Name of the attribute.
value - Value of the attribute.
Returns:
Previous value of the attribute or null if the attribute didn't exist.

removeAttribute

public Object removeAttribute(String name)
Remove an attribute from this ApfloatContext.

Parameters:
name - Name of the attribute.
Returns:
Value of the attribute or null if the attribute didn't exist.

getAttributeNames

public Enumeration<String> getAttributeNames()
Get names of all attributes for this ApfloatContext.

Returns:
Names of all attributes as strings.

loadProperties

public static Properties loadProperties()
                                 throws ApfloatRuntimeException
Loads properties from a properties file or resource bundle. First the ResourceBundle by the name "apfloat" is located, then all properties found from that resource bundle are put to a Properties object.

The resource bundle is found basically using the following logic (note that this is standard Java ResourceBundle functionality), in this order whichever is found first:

  1. From the class named apfloat (that should be a subclass of ResourceBundle), in the current class path
  2. From the file "apfloat.properties" in the current class path

Returns:
Properties found in the "apfloat" resource bundle, or an empty Properties object, if the resource bundle is not found.
Throws:
ApfloatRuntimeException

getDefaultExecutorService

public static ExecutorService getDefaultExecutorService()
Returns a new instance of a default ExecutorService.

Returns:
A new instance of a default ExecutorService.
Since:
1.3

setProperties

public void setProperties(Properties properties)
                   throws ApfloatRuntimeException
Set the values of all properties as strings. The names of the properties can be all of the constants defined above.

Parameters:
properties - The properties.
Throws:
ApfloatRuntimeException

clone

public Object clone()
Creates a copy of this object.

The clone has the same BuilderFactory and FilenameGenerator members and the same shared memory lock and ExecutorService as the original ApfloatContext.

A shallow copy of the property set and the attribute set is created. Thus setting a property or attribute on the clone will not set it in the original object. Since the actual attributes (values) are shared, if an attribute is mutable and is modified in the clone, the modified value will appear in the original also.

Overrides:
clone in class Object
Returns:
A mostly shallow copy of this object.