package memory.api;

/**
 * Allocates and frees dynamic memory.
 */
public interface Allocator {

  /**
   * Allocates memory space
   * <p>
   * This method allocates <i>size</i> bytes and returns a pointer to the
   * allocated memory. The memory is not cleared. The value returned is a 
   * pointer to the allocated memory, which is suitably aligned for any kind of
   * variable, or <code>NULL</code> if the request fails.
   *
   * @param size the amount of memory requested
   * @return pointer to the allocated memory
   */
  any alloc(int size);

  /**
   * Frees memory space
   * <p>
   * This method frees  the  memory space pointed to by <code>addr</code>, which
   * must have been returned by a previous call to 
   * {@link Allocator#alloc(int) alloc}. Otherwise, or if free has already been 
   * called before with the same <code>addr</code>, the behavior is undefined.
   *
   * @param addr the pointer to be freed. May be <code>NULL</code>, in which 
   *      case this operation does nothing.
   */
  void free(any addr);
}