package vtk;

/**
 * This interface provide all the methods needed for the management of vtkObject
 * in the Java world. They are used internally inside the generated Java code of
 * the VTK objects to keep track of the reference count of the corresponding VTK
 * C++ object and therefore allow to release memory when it became possible.
 *
 * Only the 3 following methods should be called by the user: - gc(boolean) : to
 * run the garbage collection - getAutoGarbageCollector() : to get the EDT
 * garbage collection scheduler - deleteAll() : to free any remaining VTK
 * object.
 *
 * @author sebastien jourdain - sebastien.jourdain@kitware.com
 */
public interface vtkJavaMemoryManager {
  /**
   * Create or return an existing instance of the vtkObject that corresponds
   * to the pointer id vtkId.
   *
   * @param vtkId
   *            is used to uniquely identify a vtkObject inside the C++ layer.
   *
   * @return a java object that map its underlying C++ instance.
   */
  vtkObjectBase getJavaObject(Long vtkId);

  /**
   * Store the Java instance of a vtkObject inside a weak pointer map.
   *
   * @param id
   *            is used to uniquely identify a vtkObject inside the C++ layer.
   * @param obj
   *            is the Java instance that is stored inside a WeakPointer of
   *            the map.
   */
  void registerJavaObject(Long id, vtkObjectBase obj);

  /**
   * If found the Java object is removed from the map and we decrease the
   * reference count of the underneath C++ instance.
   *
   * @param id
   */
  void unRegisterJavaObject(Long id);

  /**
   * Execute the garbage collection in the Java + VTK context to release Java
   * instance that are not used anymore which keep holding a C++ instance
   * around.
   *
   * @param debug
   *            allow to add extra information inside the return object such
   *            as the class name of the objects lefts as well as their
   *            numbers.
   *
   * @return an information object that provide useful information for
   *         statistic or debugging purpose.
   */
  vtkReferenceInformation gc(boolean debug);

  /**
   * @return an helper class that allow to trigger the garbage collector at a
   *         given frequency inside the EDT.
   */
  vtkJavaGarbageCollector getAutoGarbageCollector();

  /**
   * This method will clean up the Map of the Java objects and will release
   * any vtkObject that was held by a Java one. This will prevent you from
   * using any existing VTK Java object.
   *
   * @return the size of the map that we cleared
   */
  int deleteAll();

  /**
   * @return the number of vtkObject that are currently used inside the Java
   *         world.
   */
  int getSize();

  /**
   * @return the vtkReferenceInformation object generated by the last gc() call
   */
  vtkReferenceInformation getLastReferenceInformation();
}