Getting Started With BigMemory Go

BigMemory Go version 4.0.x

Installing BigMemory Go

Installing BigMemory Go is as easy as downloading the kit and ensuring that the correct files are on your application's classpath. The only platform requirement is using JDK 1.6 or higher.

1. If you do not have a BigMemory Go kit, download it from here.

   The kit is packaged as a tar.gz file. Unpack it on the command line or with the appropriate decompression application.

2. The following JARs are found in the kit's lib directory and must be added to your application's classpath:

   • bigmemory-<version>.jar – This is the main JAR to enable BigMemory.

   • ehcache-ee-<version>.jar – This file contains the API to BigMemory Go.

   • slf4j-api-<version>.jar – This file is the bridge, or logging facade, to the BigMemory Go logging framework.

   • slf4j-jdk14-<version>.jar – This is a binding JAR for the provided SLF4J logging framework, java.util.logging. Binding JARs for other frameworks are available from the SLF4J website.

3. Save the BigMemory Go license-key file to the BigMemory Go home directory. This file, called terracotta-license.key, was attached to an email you received after registering for the BigMemory Go download.

   Alternatively, you can add the license-key file to your application's classpath, or specify it with the following Java system property:

   -Dcom.tc.productkey.path=/path/to/terracotta-license.key
   

4. BigMemory Go uses Ehcache as its user-facing interface. To configure BigMemory Go, create or update an Ehcache configuration file to specify how much off-heap in-memory storage your want to use. You may also configure BigMemory to write data to a local disk store for fast restart. For example:

   <ehcache xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="http://ehcache.org/ehcache.xsd"
        name="myBigMemoryGoConfig">
   
     <!-- Tell BigMemory where to write its data to disk. -->
     <diskStore path="/path/to/my/disk/store/directory"/>
   
     <!-- set "maxBytesLocalOffHeap" to the amount of off-heap memory you
     want to use.  This memory is invisible to the Java garbage collector,
     providing gigabytes to terabytes of in-memory data without garbage
     collection pauses. --> 
     <cache name="myBigMemoryGoStore"
           maxBytesLocalHeap="512M"
           maxBytesLocalOffHeap="32G">
       <!-- Tell BigMemory to use the "localRestartable" persistence
       strategy for fast restart (optional). -->
       <persistence strategy="localRestartable"/>
     </cache>
   </ehcache>
   

   Set maxBytesLocalOffHeap to the amount of off-heap storage you want to use. Depending on your data and how much physical RAM you have available, you can use just a few gigabytes to multiple terabytes of off-heap memory in a single JVM for ultra-fast access with no garbage collection pauses—and you get up to 32GB for free.

   Name this configuration file ehcache.xml and place it in the top-level of your classpath.

   For more information on configuration options, refer to the configuration documentation and to the reference ehcache.xml configuration file in the config-samples directory of the BigMemory Go kit.

5. Use the -XX:MaxDirectMemorySize Java option to allocate enough direct memory in the JVM to accomodate the off-heap storage specified in your configuration, plus at least 250MB to allow for other direct memory usage that might occur in your application. For example:

   -XX:MaxDirectMemorySize=33G
   

   Set MaxDirectMemorySize to the amount of BigMemory you have. For more information about this step, refer to Allocating Direct Memory in the JVM.

   Also, allocate at least enough heap using the -Xmx Java option to accomodate the on-heap storage specified in your configuration, plus enough extra heap to run the rest of your application. For example:

   -Xmx1g
   

6. Look through the code samples in the documentation and in the download kit for examples of how to employ the various features and capabilities of BigMemory Go.

Configuring BigMemory Go

For a general overview to configuring BigMemory Go, see this introductory page. Specific configuration topics are introduced below.

Automatic Resource Control

Automatic Resource Control (ARC) gives you fine-grained controls for tuning performance and enabling trade-offs between throughput, latency and data access. Independently adjustable configuration parameters include differentiated tier-based sizing and pinning hot or eternal data in the most effective tier.

Dynamically Sizing Stores

Tuning often involves sizing stores appropriately. There are a number of ways to size the different BigMemory Go data tiers using simple configuration sizing attributes. The sizing page explains how to tune tier sizing by configuring dynamic allocation of memory and automatic balancing.

Pinning Data

One of the most important aspects of running an in-memory data store involves managing the life of the data in each BigMemory Go tier. See the data-life page for more information on the pinning, expiration, and eviction of data.

Fast Restartability

BigMemory Go has full fault tolerance, allowing for continuous access to in-memory data after a planned or unplanned shutdown, with the option to store a fully consistent record of the in-memory data on the local disk at all times. The fast-restart page covers data persistence, fast restartability, and using the local disk as a storage tier for in-memory data (both heap and off-heap stores).

Using the BigMemory Go API

BigMemory Go provides a full-featured API. See the code-samples page for a beginner's view of using the API. Selected advanced API features are introduced below.

Search

Search billions of entries—gigabytes, even terabytes of data—with results returned in less than a second. Data is indexed without significant overhead, and features like "GroupBy' are included.

The Search API allows you to execute arbitrarily complex queries against data with pre-built indexes. The development of alternative indexes on values provides the ability for data to be looked up based on multiple criteria instead of just keys.

Transactional Caching

Transactional modes are a powerful extension for performing atomic operations on data stores, keeping your data in sync with your database.

The transactions page covers the background and configuration information for BigMemory Go transactional modes. Explicit Locking is another API that can be used as a custom alternative to XA Transactions or Local transactions.

Administration and Monitoring

The Terracotta Management Console (TMC) is a web-based monitoring and administration application for tuning cache usage, detecting errors, and providing an easy-to-use access point to integrate with production management systems.

As an alternative to the TMC, standard JMX-based administration and monitoring is available.

For logging, BigMemory Go uses the flexible SLF4J logging framework.

Learn More About How BigMemory Go Works

• Code Samples to learn what you can do with BigMemory Go.

• Configuration Overview to learn more about how BigMemory Go is configured.

• BigMemory Go Architecture to learn more about how BigMemory Go works.