:mod:`memorymonitor`
====================

.. py:module:: memorymonitor

.. autoapi-nested-parse::

   Memory monitoring helpers






.. py:exception:: AllocationError

   Bases: :py:obj:`Exception`

   Catchall exception for allocation related errors.

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


.. py:class:: 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)


   .. py:method:: 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)


   .. py:method:: __enter__() -> AllocationAlarm

      Enables the alarm.


   .. py:method:: __exit__() -> None

      Automatically disables the allocation alarm when exiting a context. See
      :ref:`lifetime-and-contextmanagers` for more info.



.. py:class:: 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)


   .. py:attribute:: bytes_per_block
      :annotation: :int

      Number of bytes per block


   .. py:method:: __enter__() -> AllocationSize

      Clears counts and resumes tracking.


   .. py:method:: __exit__() -> None

      Automatically pauses allocation tracking when exiting a context. See
      :ref:`lifetime-and-contextmanagers` for more info.


   .. py:method:: __len__() -> int

      Returns the number of allocation buckets.

      This allows you to::

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


   .. py:method:: __getitem__(index: int) -> Optional[int]

      Returns the allocation count for the given bucket.

      This allows you to::

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