Low-level interface to the Criterium native agent for allocation tracking.
This namespace provides the core implementation for interacting with the agent that tracks JVM heap allocations. It manages agent state, handles allocation records, and provides primitives for the high-level API.
Key Components:
Implementation Notes:
WARNING: The agent must be loaded before calling most functions in this namespace. Use criterium.agent.runtime/load-agent! or -agentpath JVM arg.
This is an internal implementation namespace. Most users should use criterium.agent instead.
Low-level interface to the Criterium native agent for allocation tracking. This namespace provides the core implementation for interacting with the agent that tracks JVM heap allocations. It manages agent state, handles allocation records, and provides primitives for the high-level API. Key Components: - Native Agent Commands: Protocol for controlling agent behavior - State Management: Track and validate agent state transitions - Allocation Recording: Capture and store allocation events - Data Processing: Transform raw allocation data into usable records Implementation Notes: - Uses wrapper namespace for zero-allocation Agent access - Manages thread-local and global agent state - Optimized for minimal allocation overhead during tracing - Handles concurrent access to shared state - Safe to load even when agent classes are not available WARNING: The agent must be loaded before calling most functions in this namespace. Use criterium.agent.runtime/load-agent! or -agentpath JVM arg. This is an internal implementation namespace. Most users should use criterium.agent instead.
(agent-command cmd)Send a command to the native agent.
Commands are sent via JNI and may block until the agent responds. See commands map for valid command values.
Implementation Notes:
Send a command to the native agent. Commands are sent via JNI and may block until the agent responds. See commands map for valid command values. Implementation Notes: - Thread-safe but may synchronize on agent state - May trigger state transitions - Command acknowledgement is synchronous
(agent-state)Get current agent state as a keyword.
Returns :not-attached if agent is not loaded or not available.
Implementation Notes:
Get current agent state as a keyword. Returns :not-attached if agent is not loaded or not available. Implementation Notes: - Thread-safe but uncoordinated - Returns state keywords from states map
(allocation-finish-marker)Create a marker allocation to track end of allocation sequence.
Create a marker allocation to track end of allocation sequence.
(allocation-freed? record)Predicate that returns true if the allocation record indicates the object was freed.
An object is considered freed when it has been garbage collected during the allocation tracking session. This helps identify temporary allocations vs retained objects.
Parameters: record - The allocation record to check
Returns true if the record indicates the object was freed during tracking.
Predicate that returns true if the allocation record indicates the object was freed. An object is considered freed when it has been garbage collected during the allocation tracking session. This helps identify temporary allocations vs retained objects. Parameters: record - The allocation record to check Returns true if the record indicates the object was freed during tracking.
(allocation-on-thread? thread-id)Returns a predicate function for filtering allocation records by thread.
The returned function takes an allocation record and returns true if the allocation occurred on the specified thread. Useful for filtering allocation records to analyze per-thread behavior.
Parameters: thread-id - Thread ID to match against allocation records
Returns a function that takes an allocation record and returns true if the record's thread matches the specified thread-id.
Returns a predicate function for filtering allocation records by thread. The returned function takes an allocation record and returns true if the allocation occurred on the specified thread. Useful for filtering allocation records to analyze per-thread behavior. Parameters: thread-id - Thread ID to match against allocation records Returns a function that takes an allocation record and returns true if the record's thread matches the specified thread-id.
(allocation-start-marker)Create a marker allocation to track start of allocation sequence.
Used to synchronize the start of allocation tracking by creating a recognizable allocation pattern.
Implementation Notes:
Create a marker allocation to track start of allocation sequence. Used to synchronize the start of allocation tracking by creating a recognizable allocation pattern. Implementation Notes: - Creates a specific allocation pattern - Filtered from final results - Used for state transition timing
(allocation-tracing-active?)Test if allocation tracing is currently active.
Returns true only when the agent is in the :allocation-tracing-active state and fully initialized.
Implementation Notes:
Test if allocation tracing is currently active. Returns true only when the agent is in the :allocation-tracing-active state and fully initialized. Implementation Notes: - Thread-safe state check - Used to verify tracing preconditions - Optimized for frequent checking
(allocation-tracing-start!)Initialize and start allocation tracing.
Sequence:
Implementation Notes:
Initialize and start allocation tracing. Sequence: 1. Send start command to agent 2. Wait for agent state transition 3. Force GC to clear existing allocations 4. Create start marker and verify state Implementation Notes: - Blocks until tracing is active - Creates synchronization allocations - May timeout if agent doesn't respond - Thread-safe but should not be called concurrently
(allocation-tracing-stop!)Stop allocation tracing and collect final results.
Sequence:
Implementation Notes:
Stop allocation tracing and collect final results. Sequence: 1. Send stop command to agent 2. Create finish marker allocation 3. Force GC to flush remaining allocations 4. Wait for agent to finish processing Implementation Notes: - Blocks until processing complete - Creates marker allocations - Thread-safe but should not be called concurrently - May timeout if agent doesn't respond
(allocations-summary records)Returns a summary of allocation statistics for the given records.
Takes a sequence of allocation records and returns a map with: {:num-allocated - Total number of objects allocated :num-freed - Number of allocated objects that were freed :allocated-bytes - Total bytes allocated :freed-bytes - Total bytes from freed objects}
Parameters: records - Sequence of allocation records to summarize
Returns a map containing allocation statistics.
Returns a summary of allocation statistics for the given records.
Takes a sequence of allocation records and returns a map with:
{:num-allocated - Total number of objects allocated
:num-freed - Number of allocated objects that were freed
:allocated-bytes - Total bytes allocated
:freed-bytes - Total bytes from freed objects}
Parameters:
records - Sequence of allocation records to summarize
Returns a map containing allocation statistics.(attached?)Returns true if the Criterium native agent is currently loaded.
Checks whether the agent was loaded via -agentpath JVM arguments or programmatically via load-agent!. The agent is considered attached if its state is anything other than :not-attached.
This is the core implementation used by criterium.agent/attached? and criterium.agent/loaded?.
Returns true if the Criterium native agent is currently loaded. Checks whether the agent was loaded via -agentpath JVM arguments or programmatically via load-agent!. The agent is considered attached if its state is anything other than :not-attached. This is the core implementation used by criterium.agent/attached? and criterium.agent/loaded?.
(collect-method-call-tree)Retrieve the method call tree from the agent.
Sends the report command and waits for the agent to send the MethodCall trees via the data callback. The trees are accumulated in the method-call-tree atom.
Returns a vector of call tree root nodes.
Retrieve the method call tree from the agent. Sends the report command and waits for the agent to send the MethodCall trees via the data callback. The trees are accumulated in the method-call-tree atom. Returns a vector of call tree root nodes.
(internal->class-name internal-name)Convert an internal JVM class name to standard Java/Clojure class name.
Parameter: internal-name - String in JVM internal format (e.g. 'Ljava/lang/String;') Also handles primitive arrays ('[B', '[I', etc.) and object arrays ('[Ljava/lang/String;')
Return: Standard class name with dot notation (e.g. 'java.lang.String') or array notation (e.g. 'byte[]', 'String[]')
Example: (internal->class-name "Ljava/util/List;") => "java.util.List" (internal->class-name "[B") => "byte[]" (internal->class-name "[Ljava/lang/String;") => "java.lang.String[]"
Convert an internal JVM class name to standard Java/Clojure class name.
Parameter:
internal-name - String in JVM internal format (e.g. 'Ljava/lang/String;')
Also handles primitive arrays ('[B', '[I', etc.) and
object arrays ('[Ljava/lang/String;')
Return:
Standard class name with dot notation (e.g. 'java.lang.String')
or array notation (e.g. 'byte[]', 'String[]')
Example:
(internal->class-name "Ljava/util/List;")
=> "java.util.List"
(internal->class-name "[B")
=> "byte[]"
(internal->class-name "[Ljava/lang/String;")
=> "java.lang.String[]"Atom containing the method call tree roots from the last tracing session.
The value is a vector of tree nodes. Each tree node is a map: {:class - Class name (JVM internal format converted to standard) :method - Method name :file - Source file name (may be nil) :line - Line number (-1 if unknown) :call-count - Number of times this call path was executed :children - Vector of child call nodes}
Multiple roots occur when separate call chains are traced (e.g., user code followed by the tracing infrastructure's stop function).
Atom containing the method call tree roots from the last tracing session.
The value is a vector of tree nodes. Each tree node is a map:
{:class - Class name (JVM internal format converted to standard)
:method - Method name
:file - Source file name (may be nil)
:line - Line number (-1 if unknown)
:call-count - Number of times this call path was executed
:children - Vector of child call nodes}
Multiple roots occur when separate call chains are traced (e.g., user code
followed by the tracing infrastructure's stop function).(method-tracing-active?)Test if method tracing is currently active.
Returns true only when the agent is in the :method-tracing-active state.
Test if method tracing is currently active. Returns true only when the agent is in the :method-tracing-active state.
(method-tracing-finish-marker)Call the method tracing finish marker.
This generates a MethodEntry event that the agent uses to transition from :method-tracing-stopping to :method-tracing-stopped state.
Call the method tracing finish marker. This generates a MethodEntry event that the agent uses to transition from :method-tracing-stopping to :method-tracing-stopped state.
(method-tracing-start!)Initialize and start method call tracing.
Sends the start command to the agent, waits for events to be enabled, then calls the start marker to synchronize the transition to active state. This ensures all method events after the marker are captured.
Implementation Notes:
Initialize and start method call tracing. Sends the start command to the agent, waits for events to be enabled, then calls the start marker to synchronize the transition to active state. This ensures all method events after the marker are captured. Implementation Notes: - Blocks until tracing is active - Uses marker-based synchronization for precise event capture - May timeout if agent doesn't respond - Thread-safe but should not be called concurrently
(method-tracing-start-marker)Call the method tracing start marker.
This generates a MethodEntry event that the agent uses to transition from :method-tracing-starting to :method-tracing-active state.
Call the method tracing start marker. This generates a MethodEntry event that the agent uses to transition from :method-tracing-starting to :method-tracing-active state.
(method-tracing-starting?)Test if method tracing is in starting state (waiting for start marker).
Test if method tracing is in starting state (waiting for start marker).
(method-tracing-stop!)Stop method call tracing.
Sends the stop command to the agent, then calls the finish marker to ensure all user code events are captured before transitioning to stopped.
Implementation Notes:
Stop method call tracing. Sends the stop command to the agent, then calls the finish marker to ensure all user code events are captured before transitioning to stopped. Implementation Notes: - Blocks until processing complete - Uses marker-based synchronization for precise event capture - Thread-safe but should not be called concurrently - May timeout if agent doesn't respond
Atom containing the current set of allocation records.
Records are captured during allocation tracing and stored here until retrieved. The atom is cleared at the start of each tracing session.
Structure: Vector of maps, each containing allocation details like:
Atom containing the current set of allocation records. Records are captured during allocation tracing and stored here until retrieved. The atom is cleared at the start of each tracing session. Structure: Vector of maps, each containing allocation details like: - :object-type - Class of allocated object - :object_size - Size in bytes - :call-* - Allocation call site information - :alloc-* - Allocator information - :thread - Thread ID - :freed - GC status
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |