AllocationContext (Blazegraph Database Platform 2.1.5 API)

java.lang.Object
- com.bigdata.rwstore.sector.AllocationContext

All Implemented Interfaces:

ICounterSetAccess, IAllocationContext, IAllocationManagerStore, IStreamStore, IAllocationManager, IHistoryManager, IStore, IMemoryManager
```
public class AllocationContext
extends Object
implements IAllocationContext, IMemoryManager
```
The AllocationContext is used to maintain a handle on allocations made within some specific environment (context). In this way, clearing a context will return all allocations to the more general pool. There are two obvious implementation strategies:
1. Retaining set of addresses allocated
2. Retaining a copy of the allocated bits
If it was not for the BLOB implementations which require length data to manage the freeing of an allocation, it would be efficient to maintain copies of the allocation bits. This remains an option for the future but requires a relatively complex callback protocol. For this reason, the initial implementation maintains a set of allocated addresses.
Author:

Martyn Cutcher

Constructor Summary

Constructors
Constructor and Description

AllocationContext(AllocationContext parent)

AllocationContext(MemoryManager root, boolean isolated)

Constructors
Constructor and Description
`AllocationContext(AllocationContext parent)`
`AllocationContext(MemoryManager root, boolean isolated)`

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`abortContext(IAllocationContext context)` Indicates that the allocation context will no longer be used and that the allocations made within the context should be discarded.
`long`	`alloc(byte[] buf, int size, IAllocationContext context)` Writes data on the store.
`long`	`allocate(ByteBuffer data)` Version of `IMemoryManager.allocate(ByteBuffer, boolean)` which is either blocking or non-blocking depending on whether or not the memory manager is set in a blocking mode.
`long`	`allocate(ByteBuffer data, boolean blocks)` Allocates space on the backing resource and copies the provided data.
`long`	`allocate(ByteBuffer data, IAllocationContext context)`
`long`	`allocate(int nbytes)` Return the address of a new allocation sufficient to store the specified number of bytes of application data.
`long`	`allocate(int nbytes, boolean blocks)` Return the address of a new allocation sufficient to store the specified number of bytes of application data.
`int`	`allocationSize(long addr)` Return the size of the application data for the allocation with the given address.
`void`	`checkActive()`
`int`	`checkDeferredFrees(AbstractJournal abstractJournal)` This method is invoked during the commit protocol and gives the backing store an opportunity to check whether storage associated with deferred frees can now be released.
`void`	`clear()` Clears all current allocations.
`void`	`close()` Close the backing storage.
`void`	`commit()` Global commit on the backing store.
`IMemoryManager`	`createAllocationContext()` Create a child allocation context within which the caller may make and release allocations.
`void`	`delete(long addr, IAllocationContext context)` Delete the data associated with the address within the allocation context.
`void`	`detachContext(IAllocationContext context)` Indicates that the allocation context will no longer be used, but that the allocations made within the context should be preserved.
`void`	`free(long addr)` Frees the address and makes available for recycling
`void`	`free(long addr, IAllocationContext context)`
`void`	`free(long addr, int size)` Frees allocated storage (clears the bit to enable recycling after the next commit).
`ByteBuffer[]`	`get(long addr)` Return an array of `ByteBuffer`s providing an updatable view onto the backing allocation.
`long`	`getAllocationCount()` The #of allocation spanned by this allocation context (including any any child allocation contexts).
`int`	`getAssociatedSlotSize(int addr)`
`Lock`	`getCommitLock()` Optionally return a `Lock` that must be used (when non- `null`) to make the `IStore.commit()` / `IStore.postCommit()` strategy atomic.
`CounterSet`	`getCounters()` Return performance counters.
`void`	`getData(long l, byte[] buf)` Read data of a known size from the store.
`InputStream`	`getInputStream(long addr)` Return an input stream from which a previously written stream may be read back.
`long`	`getLastReleaseTime()` If history is retained this returns the time for which data was most recently released.
`int`	`getMaxSectors()` The maximum number of backing buffers which may be allocated by the `IMemoryManager` and `Integer.MAX_VALUE` if there is no effective limit on the #of backing buffers which may be allocated.
`IPSOutputStream`	`getOutputStream()` Return an output stream which can be used to write on the backing store.
`IPSOutputStream`	`getOutputStream(IAllocationContext context)` Return an output stream which can be used to write on the backing store within the given allocation context.
`long`	`getPhysicalAddress(long addr)` Determine the unencoded physical address
`int`	`getSectorCount()` The #of backing buffers in use.
`int`	`getSectorSize()` The size of a backing buffer in bytes.
`long`	`getSlotBytes()` Return the #of bytes of consumed by allocation slots allocated against this `IMemoryManager` (including any child allocation contexts).
`File`	`getStoreFile()` Retrieves store file.
`long`	`getUserBytes()` Return the #of bytes of application data allocated against this `IMemoryManager` (including any child allocation contexts).
`boolean`	`isCommitted(long addr)` Return `true` iff the allocation having that address is flagged as committed.
`boolean`	`isIsolated()`
`IAllocationContext`	`newAllocationContext(boolean isolated)` Creates a context to be used to isolate updates to within the context until it is released to the parent environment.
`IRawTx`	`newTx()` A hook used to support session protection by incrementing and decrementing a transaction counter within the `IStore`.
`void`	`postCommit()` Hook that supports synchronization with an external commit before which a rollback to "pre-commit" state is supported.
`byte[]`	`read(long addr)` Return a copy of the data stored at that address.
`void`	`registerExternalCache(ConcurrentWeakValueCache<Long,ICommitter> historicalIndexCache, int byteCount)` Call made from AbstractJournal to register the cache used.
`void`	`release()`
`long`	`saveDeferrals()` Saves the current list of delete blocks, returning the address allocated.
`long`	`write(ByteBuffer data, IAllocationContext context)` Write the data within the allocation context.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - AllocationContext
```
public AllocationContext(MemoryManager root,
                 boolean isolated)
```
  - AllocationContext
```
public AllocationContext(AllocationContext parent)
```
- Method Detail
  - checkActive
```
public final void checkActive()
```
    Specified by:
    
    checkActive in interface IAllocationContext
  - isIsolated
```
public boolean isIsolated()
```
    Specified by:
    
    isIsolated in interface IAllocationContext
  - allocate
```
public long allocate(ByteBuffer data)
```
    Description copied from interface: IMemoryManager
    
    Version of IMemoryManager.allocate(ByteBuffer, boolean) which is either blocking or non-blocking depending on whether or not the memory manager is set in a blocking mode.
    
    Specified by:
    
    allocate in interface IMemoryManager
    
    Parameters:
    data - The data will be copied to the backing resource. For each buffer in this array, the position will be advanced to the limit.
  - allocate
```
public long allocate(ByteBuffer data,
            boolean blocks)
```
    Description copied from interface: IMemoryManager
    
    Allocates space on the backing resource and copies the provided data.
    
    Specified by:
    
    allocate in interface IMemoryManager
    
    Parameters:
    data - The data will be copied to the backing resource. For each buffer in this array, the position will be advanced to the limit.
    blocks - When true the request will block until the memory is available for the allocation.
    
    Returns:
    the address to be passed to the get method to retrieve the data.
  - allocate
```
public long allocate(int nbytes)
```
    Description copied from interface: IMemoryManager
    
    Return the address of a new allocation sufficient to store the specified number of bytes of application data. This is the blocking version of IMemoryManager.allocate(int).
    
    Specified by:
    
    allocate in interface IMemoryManager
    
    Parameters:
    nbytes - The size of the allocation request.
    
    Returns:
    The address of the allocation.
  - allocate
```
public long allocate(int nbytes,
            boolean blocks)
```
    Description copied from interface: IMemoryManager
    
    Return the address of a new allocation sufficient to store the specified number of bytes of application data.
    
    Specified by:
    
    allocate in interface IMemoryManager
    
    Parameters:
    nbytes - The size of the allocation request.
    blocks - When true the method will block until the allocation request can be satisfied. When false a MemoryManagerOutOfMemory will be thrown.
    
    Returns:
    The address of the allocation.
  - clear
```
public void clear()
```
    Description copied from interface: IMemoryManager
    
    Clears all current allocations. Clearing an allocation context makes the backing heap storage available to immediate reallocation. Clearing the allocation context of the top-level IMemoryManager will release any direct ByteBuffers back to the pool from which they were allocated.
    CAUTION: Do not clear an allocation context until you know that all threads with access to that allocation context have either been terminated or released their reference to that allocation context.
    
    Specified by:
    
    clear in interface IMemoryManager
  - free
```
public void free(long addr)
```
    Description copied from interface: IMemoryManager
    
    Frees the address and makes available for recycling
    
    Specified by:
    
    free in interface IMemoryManager
    
    Parameters:
    addr - to be freed
  - get
```
public ByteBuffer[] get(long addr)
```
    Description copied from interface: IMemoryManager
    Return an array of ByteBuffers providing an updatable view onto the backing allocation.
    The ByteBuffer[] return enables the handling of blobs that span more than a single slot, without the need to create an intermediate ByteBuffer. This method is designed for use with zero-copy NIO. Furthermore, since the ByteBuffers in the returned array are not read-only, they can be updated directly. In this way the IMemoryManager.allocate(int) can be used in conjunction with get to provide more flexibility when storing data.
    Using ByteBuffer:put the returned array can be efficiently copied to another ByteBuffer:
```
 ByteBuffer mybb;
 ByteBuffer[] bufs = get(addr);
 for (ByteBuffer b : bufs) {
        mybb.put(b);
 }
 
```
    CAUTION: Do not hold onto the ByteBuffer longer than is necessary. If the allocation is released by IMemoryManager.free(long) or IMemoryManager.clear(), then the memory backing the ByteBuffer could be reallocated by another DirectBufferPool consumer.
    Specified by:
    
    get in interface IMemoryManager
    
    Parameters:
    addr - An previously allocated address.
    
    Returns:
    array of ByteBuffers
  - read
```
public byte[] read(long addr)
```
    Description copied from interface: IMemoryManager
    
    Return a copy of the data stored at that address. This method is intended for use with patterns where the IMemoryManager is treated as a persistence store.
    
    Specified by:
    
    read in interface IMemoryManager
    
    Parameters:
    addr - The address.
    
    Returns:
    A copy of the data stored at that address.
  - createAllocationContext
```
public IMemoryManager createAllocationContext()
```
    Description copied from interface: IMemoryManager
    
    Create a child allocation context within which the caller may make and release allocations. TODO Why is the return not an IAllocationContext as well (that is, why does IMemoryManager not extend IAllocationContext ). Also, note that IStore.commit() is similar to IAllocationManager.detachContext(IAllocationContext).
    
    Specified by:
    
    createAllocationContext in interface IMemoryManager
  - allocationSize
```
public int allocationSize(long addr)
```
    Description copied from interface: IMemoryManager
    
    Return the size of the application data for the allocation with the given address.
    
    Specified by:
    
    allocationSize in interface IMemoryManager
    
    Parameters:
    addr - The address.
    
    Returns:
    The #of bytes of in the applications allocation request.
  - getAllocationCount
```
public long getAllocationCount()
```
    Description copied from interface: IMemoryManager
    
    The #of allocation spanned by this allocation context (including any any child allocation contexts).
    
    Specified by:
    
    getAllocationCount in interface IMemoryManager
  - getSlotBytes
```
public long getSlotBytes()
```
    Description copied from interface: IMemoryManager
    
    Return the #of bytes of consumed by allocation slots allocated against this IMemoryManager (including any child allocation contexts).
    
    Specified by:
    
    getSlotBytes in interface IMemoryManager
  - getUserBytes
```
public long getUserBytes()
```
    Description copied from interface: IMemoryManager
    
    Return the #of bytes of application data allocated against this IMemoryManager (including any child allocation contexts). Due to the overhead of the storage allocation scheme, this value may be smaller than IMemoryManager.getSlotBytes().
    
    Specified by:
    
    getUserBytes in interface IMemoryManager
  - getCounters
```
public CounterSet getCounters()
```
    Description copied from interface: ICounterSetAccess
    
    Return performance counters.
    
    Specified by:
    
    getCounters in interface ICounterSetAccess
  - getOutputStream
```
public IPSOutputStream getOutputStream()
```
    Description copied from interface: IStreamStore
    
    Return an output stream which can be used to write on the backing store. You can recover the address used to read back the data from the IPSOutputStream.
    
    Specified by:
    
    getOutputStream in interface IStreamStore
    
    Returns:
    The output stream.
  - getOutputStream
```
public IPSOutputStream getOutputStream(IAllocationContext context)
```
    Description copied from interface: IAllocationManagerStore
    
    Return an output stream which can be used to write on the backing store within the given allocation context. You can recover the address used to read back the data from the IPSOutputStream.
    
    Specified by:
    
    getOutputStream in interface IAllocationManagerStore
    
    Parameters:
    context - The context within which any allocations are made by the returned IPSOutputStream.
    
    Returns:
    an output stream to stream data to and to retrieve an address to later stream the data back.
  - getInputStream
```
public InputStream getInputStream(long addr)
```
    Description copied from interface: IStreamStore
    
    Return an input stream from which a previously written stream may be read back.
    
    Specified by:
    
    getInputStream in interface IStreamStore
    
    Parameters:
    addr - The address at which the stream was written.
    
    Returns:
    an input stream for the data for provided address
  - alloc
```
public long alloc(byte[] buf,
         int size,
         IAllocationContext context)
```
    Description copied from interface: IStore
    
    Writes data on the store.
    
    Specified by:
    
    alloc in interface IStore
    
    Returns:
    the allocated address
  - close
```
public void close()
```
    Description copied from interface: IStore
    
    Close the backing storage.
    
    Specified by:
    
    close in interface IStore
  - free
```
public void free(long addr,
        int size)
```
    Description copied from interface: IStore
    
    Frees allocated storage (clears the bit to enable recycling after the next commit).
    
    Specified by:
    
    free in interface IStore
    
    Parameters:
    addr - the storage address to be freed
  - getAssociatedSlotSize
```
public int getAssociatedSlotSize(int addr)
```
    Specified by:
    
    getAssociatedSlotSize in interface IStore
    
    Parameters:
    addr - - the address
    
    Returns:
    the size of the slot associated
  - getData
```
public void getData(long l,
           byte[] buf)
```
    Description copied from interface: IStore
    
    Read data of a known size from the store.
    
    Specified by:
    
    getData in interface IStore
    
    Parameters:
    l - the address of the data
    buf - the buffer of the size required!
  - getStoreFile
```
public File getStoreFile()
```
    Description copied from interface: IStore
    
    Retrieves store file. Can be used to delete the store after the IStore has been released
    
    Specified by:
    
    getStoreFile in interface IStore
    
    Returns:
    the File object
  - getSectorSize
```
public int getSectorSize()
```
    Description copied from interface: IMemoryManager
    
    The size of a backing buffer in bytes.
    
    Specified by:
    
    getSectorSize in interface IMemoryManager
  - getMaxSectors
```
public int getMaxSectors()
```
    Description copied from interface: IMemoryManager
    
    The maximum number of backing buffers which may be allocated by the IMemoryManager and Integer.MAX_VALUE if there is no effective limit on the #of backing buffers which may be allocated.
    
    Specified by:
    
    getMaxSectors in interface IMemoryManager
  - getSectorCount
```
public int getSectorCount()
```
    Description copied from interface: IMemoryManager
    
    The #of backing buffers in use.
    
    Specified by:
    
    getSectorCount in interface IMemoryManager
  - commit
```
public void commit()
```
    Description copied from interface: IStore
    
    Global commit on the backing store. Previously committed data which has been marked as IStore.free(long, int) is now available for recycling. However, recycling can not occur if session protection is active.
    
    Specified by:
    
    commit in interface IStore
  - getCommitLock
```
public Lock getCommitLock()
```
    Description copied from interface: IStore
    
    Optionally return a Lock that must be used (when non- null) to make the IStore.commit() / IStore.postCommit() strategy atomic.
    
    Specified by:
    
    getCommitLock in interface IStore
  - postCommit
```
public void postCommit()
```
    Description copied from interface: IStore
    
    Hook that supports synchronization with an external commit before which a rollback to "pre-commit" state is supported.
    
    Specified by:
    
    postCommit in interface IStore
  - registerExternalCache
```
public void registerExternalCache(ConcurrentWeakValueCache<Long,ICommitter> historicalIndexCache,
                         int byteCount)
```
    Description copied from interface: IHistoryManager
    
    Call made from AbstractJournal to register the cache used. This can then be accessed to clear entries when storage is made available for re-cycling.
    Note: It is not safe to clear at the point of the delete request since the data could still be loaded if the data is retained for a period due to a non-zero retention period or session protection.
    
    Specified by:
    
    registerExternalCache in interface IHistoryManager
  - checkDeferredFrees
```
public int checkDeferredFrees(AbstractJournal abstractJournal)
```
    Description copied from interface: IHistoryManager
    
    This method is invoked during the commit protocol and gives the backing store an opportunity to check whether storage associated with deferred frees can now be released. The backing store needs to reply the deferred free blocks for the commit points that will be released, mark those addresses as free, and free the logged delete blocks.
    
    Specified by:
    
    checkDeferredFrees in interface IHistoryManager
    
    Returns:
    number of addresses freed
    See Also:
    AbstractJournal#commitNow()
  - newTx
```
public IRawTx newTx()
```
    Description copied from interface: IHistoryManager
    
    A hook used to support session protection by incrementing and decrementing a transaction counter within the IStore. As long as a transaction is active we can not release data which is currently marked as freed but was committed at the point the session started.
    
    Specified by:
    
    newTx in interface IHistoryManager
  - saveDeferrals
```
public long saveDeferrals()
```
    Description copied from interface: IHistoryManager
    
    Saves the current list of delete blocks, returning the address allocated. This can be used later to retrieve the addresses of allocations to be freed.
    Writes the content of currentTxnFreeList to the store.
    These are the current buffered frees that have yet been saved into a block referenced from the deferredFreeList
    
    Specified by:
    
    saveDeferrals in interface IHistoryManager
    
    Returns:
    the address of the deferred addresses saved on the store, or zero if none.
    See Also:
    DeleteBlockCommitter
  - getLastReleaseTime
```
public long getLastReleaseTime()
```
    Description copied from interface: IHistoryManager
    
    If history is retained this returns the time for which data was most recently released. No request can be made for data earlier than this.
    
    Specified by:
    
    getLastReleaseTime in interface IHistoryManager
    
    Returns:
    latest data release time
  - abortContext
```
public void abortContext(IAllocationContext context)
```
    Description copied from interface: IAllocationManager
    
    Indicates that the allocation context will no longer be used and that the allocations made within the context should be discarded. The allocations associated with the context are discarded, as are any deletes made within the scope of that allocation context. The allocators associated with the allocation context are return to the global list of available allocators.
    
    Specified by:
    
    abortContext in interface IAllocationManager
    
    Parameters:
    context - The application object which serves as the allocation context.
  - detachContext
```
public void detachContext(IAllocationContext context)
```
    Description copied from interface: IAllocationManager
    
    Indicates that the allocation context will no longer be used, but that the allocations made within the context should be preserved. The allocations associated with the context are propagated to the parent allocation context. The IStore is the top-level parent of allocation contexts. The allocators associated with the allocation context are return to the global list of available allocators.
    
    Specified by:
    
    detachContext in interface IAllocationManager
    
    Parameters:
    context - The application object which serves as the allocation context.
  - isCommitted
```
public boolean isCommitted(long addr)
```
    Description copied from interface: IMemoryManager
    
    Return true iff the allocation having that address is flagged as committed. The caller must be holding the allocation lock in order for the result to remain valid outside of the method call.
    
    Specified by:
    
    isCommitted in interface IMemoryManager
    
    Parameters:
    addr - The address.
    
    Returns:
    true iff the address is currently committed.
  - getPhysicalAddress
```
public long getPhysicalAddress(long addr)
```
    Description copied from interface: IMemoryManager
    
    Determine the unencoded physical address
    
    Specified by:
    
    getPhysicalAddress in interface IMemoryManager
    
    Parameters:
    addr - The encoded address
    
    Returns:
    an unencoded address offset
  - allocate
```
public long allocate(ByteBuffer data,
            IAllocationContext context)
```
    Specified by:
    
    allocate in interface IMemoryManager
  - write
```
public long write(ByteBuffer data,
         IAllocationContext context)
```
    Description copied from interface: IAllocationManagerStore
    
    Write the data within the allocation context. The write is not visible outside of the allocation until the allocation context has been merged into the parent allocation context.
    
    Specified by:
    
    write in interface IAllocationManagerStore
    
    Parameters:
    data - The data.
    context - The allocation context.
    
    Returns:
    The address at which the data was written.
  - free
```
public void free(long addr,
        IAllocationContext context)
```
    Specified by:
    
    free in interface IMemoryManager
  - delete
```
public void delete(long addr,
          IAllocationContext context)
```
    Description copied from interface: IAllocationManagerStore
    
    Delete the data associated with the address within the allocation context. The delete is not visible outside of the allocation until the allocation context has been merged into the parent allocation context.
    
    Specified by:
    
    delete in interface IAllocationManagerStore
    
    Parameters:
    addr - The address whose allocation is to be deleted.
    context - The allocation context.
  - newAllocationContext
```
public IAllocationContext newAllocationContext(boolean isolated)
```
    Description copied from interface: IAllocationManager
    
    Creates a context to be used to isolate updates to within the context until it is released to the parent environment.
    
    Specified by:
    
    newAllocationContext in interface IAllocationManager
    
    Returns:
    a new IAlocationContext
  - release
```
public void release()
```
    Specified by:
    
    release in interface IAllocationContext

Class AllocationContext

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

AllocationContext

AllocationContext

Method Detail

checkActive

isIsolated

allocate

allocate

allocate

allocate

clear

free

get

read

createAllocationContext

allocationSize

getAllocationCount

getSlotBytes

getUserBytes

getCounters

getOutputStream

getOutputStream

getInputStream

alloc

close

free

getAssociatedSlotSize

getData

getStoreFile

getSectorSize

getMaxSectors

getSectorCount

commit

getCommitLock

postCommit

registerExternalCache

checkDeferredFrees

newTx

saveDeferrals

getLastReleaseTime

abortContext

detachContext

isCommitted

getPhysicalAddress

allocate

write

free

delete

newAllocationContext

release