# `wand.resource` — Global resource management

There is the global resource to manage in MagickWand API. This module implements automatic global resource management through reference counting.

exception wand.resource.DestroyedResourceError

  An error that rises when some code tries access to an already destroyed resource.

  Changed in version 0.3.0: It becomes a subtype of `wand.exceptions.WandException`.

class wand.resource.Resource

  Abstract base class for MagickWand object that requires resource management. Its all subclasses manage the resource semiautomatically and support `with` statement as well:

      with Resource() as resource:
          # use the resource...
          pass

  It doesn’t implement constructor by itself, so subclasses should implement it. Every constructor should assign the pointer of its resource data into `resource` attribute inside of `with` `allocate()` context. For example:

      class Pizza(Resource):
          '''My pizza yummy.'''

          def __init__(self):
              with self.allocate():
                  self.resource = library.NewPizza()

  Added in version 0.1.2.

  allocate()

    Allocates the memory for the resource explicitly. Its subclasses should assign the created resource into `resource` attribute inside of this context. For example:

        with resource.allocate():
            resource.resource = library.NewResource()

  c_clear_exception = NotImplemented

    (`ctypes.CFUNCTYPE`) The `ctypes` function that clears an exception of the `resource`.

    Note

    It is an abstract attribute that has to be implemented in the subclass.

  c_destroy_resource = NotImplemented

    (`ctypes.CFUNCTYPE`) The `ctypes` function that destroys the `resource`.

    Note

    It is an abstract attribute that has to be implemented in the subclass.

  c_get_exception = NotImplemented

    (`ctypes.CFUNCTYPE`) The `ctypes` function that gets an exception from the `resource`.

    Note

    It is an abstract attribute that has to be implemented in the subclass.

  c_is_resource = NotImplemented

    (`ctypes.CFUNCTYPE`) The `ctypes` predicate function that returns whether the given pointer (that contains a resource data usually) is a valid resource.

    Note

    It is an abstract attribute that has to be implemented in the subclass.

  destroy()

    Cleans up the resource explicitly. If you use the resource in `with` statement, it was called implicitly so have not to call it.

  get_exception()

    Gets a current exception instance.

    Returns:

      a current exception. it can be `None` as well if any errors aren’t occurred

    Return type:

      `wand.exceptions.WandException`

  raise_exception(stacklevel=1)

    Raises an exception or warning if it has occurred.

  property resource

    Internal pointer to the resource instance. It may raise `DestroyedResourceError` when the resource has destroyed already.

class wand.resource.ResourceLimits

  Wrapper for MagickCore resource limits. Useful for dynamically reducing system resources before attempting risky, or slow running, `Image` operations.

  For example:

      from wand.image import Image
      from wand.resource import limits

      # Use 100MB of ram before writing temp data to disk.
      limits['memory'] = 1024 * 1024 * 100
      # Reject images larger than 1000x1000.
      limits['width'] = 1000
      limits['height'] = 1000

      # Debug resources used.
      with Image(filename='user.jpg') as img:
          print('Using {0} of {1} memory'.format(limits.resource('memory'),
                                                 limits['memory']))

      # Dump list of all limits.
      for label in limits:
          print('{0} => {1}'.format(label, limits[label]))

  Available resource keys:

  - `'area'` - Maximum width * height of a pixel cache before writing to disk.

  - `'disk'` - Maximum bytes used by pixel cache on disk before exception is thrown.

  - `'file'` - Maximum cache files opened at any given time.

  - `'height'` - Maximum height of image before exception is thrown.

  - `'list_length'` - Maximum images in sequence. Only available with recent version of ImageMagick.

  - `'map'` - Maximum memory map in bytes to allocated for pixel cache before using disk.

  - `'memory'` - Maximum bytes to allocated for pixel cache before using disk.

  - `'thread'` - Maximum parallel task sub-routines can spawn - if using OpenMP.

  - `'throttle'` - Total milliseconds to yield to CPU - if possible.

  - `'time'` - Maximum seconds before exception is thrown.

  - `'width'` - Maximum width of image before exception is thrown.

  Added in version 0.5.1.

  get_resource_limit(resource)

    Get the current limit for the resource type.

    Parameters:

      resource (`str`) – Resource type.

    Return type:

      `numeric.Integral`

    Added in version 0.5.1.

  resource(resource)

    Get the current value for the resource type.

    Parameters:

      resource (`str`) – Resource type.

    Return type:

      `numeric.Integral`

    Added in version 0.5.1.

  set_resource_limit(resource, limit)

    Sets a new limit for resource type.

    Note

    The new limit value must be equal to or less than the maximum limit defined by the `policy.xml`. Any values set outside normal bounds will be ignored silently.

    Parameters:

      - resource (`str`) – Resource type.

      - limit (`numeric.Integral`) – New limit value.

    Added in version 0.5.1.

wand.resource.genesis()

  Instantiates the MagickWand API.

wand.resource.limits = <wand.resource.ResourceLimits object>

  (`ResourceLimits`) Helper to get & set Magick Resource Limits.

  Added in version 0.5.1.

wand.resource.terminus()

  Cleans up the MagickWand API.