memorymonitor – Memory monitoring helpers

exception memorymonitor.AllocationError

Bases: Exception

Catchall exception for allocation related errors.

Initialize self. See help(type(self)) for accurate signature.

class memorymonitor.AllocationAlarm(*, minimum_block_count: int = 1)

Throw an exception when an allocation of minimum_block_count or more blocks

occurs while active.

Track allocations:

import memorymonitor

aa = memorymonitor.AllocationAlarm(minimum_block_count=2)
x = 2
# Should not allocate any blocks.
with aa:
    x = 5

# Should throw an exception when allocating storage for the 20 bytes.
with aa:
    x = bytearray(20)

ignore(count: int) → AllocationAlarm

Sets the number of applicable allocations to ignore before raising the exception. Automatically set back to zero at context exit.

Use it within a with block:

# Will not alarm because the bytearray allocation will be ignored.
with aa.ignore(2):
    x = bytearray(20)

__enter__() → AllocationAlarm

Enables the alarm.

__exit__() → None

Automatically disables the allocation alarm when exiting a context. See Lifetime and ContextManagers for more info.

class memorymonitor.AllocationSize

Tracks the number of allocations in power of two buckets.

It will have 16 16-bit buckets to track allocation counts. It is total allocations meaning frees are ignored. Reallocated memory is counted twice, at allocation and when reallocated with the larger size.

The buckets are measured in terms of blocks which is the finest granularity of the heap. This means bucket 0 will count all allocations less than or equal to the number of bytes per block, typically 16. Bucket 2 will be less than or equal to 4 blocks. See bytes_per_block to convert blocks to bytes.

Multiple AllocationSizes can be used to track different code boundaries.

Track allocations:

import memorymonitor

mm = memorymonitor.AllocationSize()
with mm:
  print("hello world" * 3)

for bucket, count in enumerate(mm):
    print("<", 2 ** bucket, count)

bytes_per_block :int

Number of bytes per block

__enter__() → AllocationSize

Clears counts and resumes tracking.

__exit__() → None

Automatically pauses allocation tracking when exiting a context. See Lifetime and ContextManagers for more info.

__len__() → int

Returns the number of allocation buckets.

This allows you to:

mm = memorymonitor.AllocationSize()
print(len(mm))

__getitem__(index: int) → int | None

Returns the allocation count for the given bucket.

This allows you to:

mm = memorymonitor.AllocationSize()
print(mm[0])