com.oracle.truffle.api.instrumentation

Class AllocationReporter

java.lang.Object

com.oracle.truffle.api.instrumentation.AllocationReporter

public final class AllocationReporter
extends Object

Reporter of guest language value allocations. Language implementation ought to use this class to report all allocations and re-allocations of guest language values. An instance of this class can be obtained from Env.lookup(AllocationReporter.class). If used from compiled code paths, then the allocation reporter must be stored in a compilation final or final field.

Usage example:

@Override
protected ContextObject createContext(TruffleLanguage.Env env) {
    AllocationReporter reporter = env.lookup(AllocationReporter.class);
    return new ContextObject(reporter);
}

Object allocateNew() {
    AllocationReporter reporter = ContextObject.get(null).getReporter();
    // Test if the reporter is active, we should compute the size estimate
    if (reporter.isActive()) {
        long size = findSizeEstimate();
        reporter.onEnter(null, 0, size);
    }
    // Do the allocation itself
    Object newObject = new MyTruffleObject();
    // Test if the reporter is active,
    // we should compute the allocated object size
    if (reporter.isActive()) {
        long size = findSize(newObject);
        reporter.onReturnValue(newObject, 0, size);
    }
    return newObject;
}

Object allocateComplex() {
    AllocationReporter reporter = ContextObject.get(null).getReporter();
    // If the allocated size is a constant, onEnter() and onReturnValue()
    // can be called without a fast-path performance penalty when not active
    reporter.onEnter(null, 0, 16);
    // Do the allocation itself
    Object newObject = createComplexObject();
    // Report the allocation
    reporter.onReturnValue(newObject, 0, 16);
    return newObject;
}

Since:

0.27

Field Summary

Fields

Modifier and Type	Field and Description
static long	SIZE_UNKNOWN Constant specifying an unknown size.

Method Summary

Modifier and Type	Method and Description
void	addActiveListener(Consumer<Boolean> listener) Add a listener that is notified when active value of this reporter changes.
boolean	isActive() Test if the reporter instance is actually doing some reporting when notify methods are called.
void	onEnter(Object valueToReallocate, long oldSize, long newSizeEstimate) Report an intent to allocate a new guest language value, or re-allocate an existing one.
void	onReturnValue(Object value, long oldSize, long newSize) Report an allocation of a new one or re-allocation of an existing guest language value.
void	removeActiveListener(Consumer<Boolean> listener) Remove a listener that is notified when active value of this reporter changes.

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

SIZE_UNKNOWN

public static final long SIZE_UNKNOWN

Constant specifying an unknown size. Use it when it's not possible to estimate size of the memory being allocated.

Since:

0.27

See Also:

Constant Field Values

Method Detail

addActiveListener

public void addActiveListener(Consumer<Boolean> listener)

Add a listener that is notified when active value of this reporter changes. The listener accept method is called with the new value of AllocationReporter.isActive().

Since:

19.0

removeActiveListener

public void removeActiveListener(Consumer<Boolean> listener)

Remove a listener that is notified when active value of this reporter changes.

Since:

19.0

isActive

public boolean isActive()

Test if the reporter instance is actually doing some reporting when notify methods are called. Methods AllocationReporter.onEnter(java.lang.Object, long, long) and AllocationReporter.onReturnValue(java.lang.Object, long, long) have no effect when this method returns false. A listener can be added to listen on changes of this value.

Returns:

true when there are some AllocationListeners attached, false otherwise.

Since:

0.27

onEnter

public void onEnter(Object valueToReallocate,
                    long oldSize,
                    long newSizeEstimate)

Report an intent to allocate a new guest language value, or re-allocate an existing one. This method delegates to all registered listeners AllocationListener.onEnter(com.oracle.truffle.api.instrumentation.AllocationEvent). Only primitive types, String and TruffleObject are accepted value types. The change in memory consumption caused by the allocation is going to be newSizeEstimate - oldSize when both old size and new size are known. The change can be either positive or negative.

A call to this method needs to be followed by a call to AllocationReporter.onReturnValue(java.lang.Object, long, long) with the actual allocated value, or with the same (re-allocated) value. Nested allocations are supported, several calls to onEnter prior every sub-value allocation can be followed by the appropriate number of onReturnValue calls after the sub-values are allocated, in the opposite order.

Parameters:

valueToReallocate - null in case of a new allocation, or the value that is to be re-allocated.

oldSize - 0 in case of a new allocation, or the size in bytes of value to be re-allocated. Can be AllocationReporter.SIZE_UNKNOWN when the value size is not known.

newSizeEstimate - an estimate of the allocation size of the value which is to be created or re-allocated, in bytes. Can be AllocationReporter.SIZE_UNKNOWN when the allocation size is not known.

Since:

0.27

onReturnValue

public void onReturnValue(Object value,
                          long oldSize,
                          long newSize)

Report an allocation of a new one or re-allocation of an existing guest language value. This method notifies all registered listeners AllocationListener.onReturnValue(com.oracle.truffle.api.instrumentation.AllocationEvent) . Only primitive types, String and TruffleObject are accepted value types. The change in memory consumption caused by the allocation is newSize - oldSize when both old size and new size are known. The change can be either positive or negative.

A call to AllocationReporter.onEnter(java.lang.Object, long, long) must precede this call. In case of re-allocation, the value object passed to AllocationReporter.onEnter(java.lang.Object, long, long) must be the same instance as the value passed to this method.

Parameters:

value - the value that was newly allocated, or the re-allocated value. Must not be null.

oldSize - size in bytes of an old value, if any. Must be 0 for newly allocated values. In case of re-allocation it's the size of the original value before re-allocation. Can be AllocationReporter.SIZE_UNKNOWN when not known.

newSize - the size of the allocated value in bytes. In case of re-allocation, it's the size of the object after re-allocation. The newSize may be less than oldSize when the object size shrinks. Can be AllocationReporter.SIZE_UNKNOWN when not known.

Since:

0.27