Package pthreading

Class PThreadManager

  • public class PThreadManager
extends java.lang.Object
    Runs and manages PThreads.

    There are a number of different constructors. Some create empty managers; in others, the thread manager can be instantiated with a thread class-type from which the manager will create instances of the class during instantiation.

    In all cases, adding a thread to a thread manager will run it immediately.

    Author:
    micycle1
    See Also:
    draw(), addThread(PThread...)

    • Constructor Summary

      Constructors 
      Constructor Description
      PThreadManager​(processing.core.PApplet p)
      Constructs a new (empty) thread manager.
      PThreadManager​(processing.core.PApplet p, int targetFPS)
      Constructs a new (empty) thread manager with a user-specified default FPS for new threads.
      PThreadManager​(processing.core.PApplet p, java.lang.Class<? extends PThread> threadClass, int threadCount, int targetFPS)
      Constructs a thread manager and creates live thread instances from the given thread class (using its constructor with no additional custom args).
      PThreadManager​(processing.core.PApplet p, java.lang.Class<? extends PThread> threadClass, int threadCount, int targetFPS, java.lang.Object... args)
      Constructs a thread manager and creates running thread instances from the given thread class and given args (in contrast to addThread(Class, int, int) which does not support ags).

    • Method Summary

      Modifier and Type Method Description
      void addThread​(java.lang.Class<? extends PThread> threadClass, int threadCount)
      Adds a number of new threads to the manager using a class type (the class should extend PThread).
      void addThread​(java.lang.Class<? extends PThread> threadClass, int threadCount, int targetFPS)
      Adds a number of new threads to the manager using a class type (the class should extend PThread).
      void addThread​(java.lang.Class<? extends PThread> threadClass, int threadCount, int targetFPS, java.lang.Object... args)
      Adds a number of new threads to the manager using a class type (the class should extend PThread) and arguments.
      void addThread​(PThread... thread)
      Adds a new thread (from a PThread instance) to the manager and runs it immediately.
      void addThread​(PThread thread, int targetFPS)
      Adds a new thread (from a PThread instance) with an associated targetFPS to the manager, and runs it immediately.
      void bindDraw()
      Binds the draw() method of this thread manager to the end of the draw method of the parent PApplet, so you don't need to manually include a call to myManger.draw() in the PApplet's draw() method.
      void dispose()
      This method is bound to the parent PApplet, so that the threads are terminated properly when the sketch is closed.
      void draw()
      Draws the threads' PGraphics into the parent PApplet.
      float getAverageCalcFPS()
      First enables timing collection for each thread, then returns the average FPS of running threads' calc() loops.
      float getAverageDrawFPS()
      First enables timing collection for each thread, then returns the average FPS of running threads' draw() loops.
      int getThreadCount()
      Returns the count of the threads (both paused and running) managed by this thread manager.
      boolean isRunning()
      Is the thread manager running any threads? If pauseThreads() has been called, this method will return false.
      void pauseAndClearThread​(PThread... thread)
      Pause a given thread or threads (varargs) and clear so it will not draw visible on screen.
      void pauseAndClearThreads()
      Pauses all threads and clears them from being drawn.
      void pauseThread​(PThread... thread)
      Pause a given thread or threads (varargs).
      void pauseThreads()
      Pauses all threads.
      void relinkComputeDraw()
      Instructs the thread manager that both existing and future threads' draw() and calc() methods are to be called sequentially (default behaviour).
      void resumeThread​(PThread... thread)
      Resumes a given thread or threads (varargs).
      void resumeThreads()
      Resumes any and all paused threads.
      void stopThread​(PThread... thread)
      Stops a given thread or threads (varargs) and removes it from the thread manager (cannot be resumed).
      void stopThreads()
      Stops all threads (even if they are paused) and removes them from the thread manager, effectively resetting the thread manager.
      void unBindDraw()
      Unbinds the draw() method of this thread manager from the end of the draw method of the parent PApplet, so draw() must be called manually.
      void unlinkComputeDraw()
      Advanced: By default, each thread's draw() and calc() methods are called sequentially within the thread.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Constructor Detail

      • PThreadManager

        public PThreadManager​(processing.core.PApplet p)
        Constructs a new (empty) thread manager. The simplest constructor.
        Parameters:
        p - parent PApplet

      • PThreadManager

        public PThreadManager​(processing.core.PApplet p,
                      int targetFPS)
        Constructs a new (empty) thread manager with a user-specified default FPS for new threads. When a given thread is added to the manager and a per-thread FPS is not specified, the new thread will target the FPS as given in this constructor.
        Parameters:
        p - parent PApplet
        targetFPS - default FPS for new threads (when not specified otherwise).

      • PThreadManager

        public PThreadManager​(processing.core.PApplet p,
                      java.lang.Class<? extends PThread> threadClass,
                      int threadCount,
                      int targetFPS)
        Constructs a thread manager and creates live thread instances from the given thread class (using its constructor with no additional custom args).

        Threads can still be added later using addThread(PThread...).

        Parameters:
        p - parent PApplet
        threadClass - thread (with no arguments)
        threadCount - Number of threads of this class to spawn
        targetFPS - FPS the threads should target
        See Also:
        PThreadManager(PApplet, Class, int, int, Object...)

      • PThreadManager

        public PThreadManager​(processing.core.PApplet p,
                      java.lang.Class<? extends PThread> threadClass,
                      int threadCount,
                      int targetFPS,
                      java.lang.Object... args)
        Constructs a thread manager and creates running thread instances from the given thread class and given args (in contrast to addThread(Class, int, int) which does not support ags).

        Threads can still be added later using addThread(PThread...).

        Parameters:
        p - parent PApplet
        threadClass - A thread class you have created. It should extend the PThread class.
        threadCount - Number of threads of this class to spawn
        targetFPS - FPS the threads should target
        args - Args to pass in to the newly created threads (all threads will be constructed with the same args) -- don't include the PApplet, only your additional args.
        See Also:
        PThreadManager(PApplet, Class, int, int)

    • Method Detail

      • addThread

        public void addThread​(PThread... thread)
        Adds a new thread (from a PThread instance) to the manager and runs it immediately. Since FPS is not specified, threads added using this method inherit the targetFPS of the thread manager.
        Parameters:
        thread - Thread or threads (varargs) instances to add to the manager
        See Also:
        addThread(PThread, int)

      • addThread

        public void addThread​(PThread thread,
                      int targetFPS)
        Adds a new thread (from a PThread instance) with an associated targetFPS to the manager, and runs it immediately.
        Parameters:
        thread - Thread instance to add to the manager
        targetFPS - Per-thread targetFPS (does not affect other threads)
        See Also:
        addThread(PThread...)

      • addThread

        public void addThread​(java.lang.Class<? extends PThread> threadClass,
                      int threadCount)
        Adds a number of new threads to the manager using a class type (the class should extend PThread).
        Parameters:
        threadClass - A thread class you have created. It should extend the PThread class.
        threadCount - Number of threads of this class to spawn

      • addThread

        public void addThread​(java.lang.Class<? extends PThread> threadClass,
                      int threadCount,
                      int targetFPS)
        Adds a number of new threads to the manager using a class type (the class should extend PThread). This method is a no-arg version of addThread(Class, int, int, Object...).
        Parameters:
        threadClass - A thread class you have created. It should extend the PThread class.
        threadCount - Number of threads of this class to spawn
        targetFPS - FPS the threads should target

      • addThread

        public void addThread​(java.lang.Class<? extends PThread> threadClass,
                      int threadCount,
                      int targetFPS,
                      java.lang.Object... args)
        Adds a number of new threads to the manager using a class type (the class should extend PThread) and arguments.
        Parameters:
        threadClass - A thread class you have created. It should extend the PThread class.
        threadCount - The number of threads of this class to spawn
        targetFPS - FPS the threads should target
        args - Args to pass in to the newly created threads (all threads will be constructed with the same args) -- don't include the PApplet, only your additional args.

      • pauseThreads

        public void pauseThreads()
        Pauses all threads. Note that paused threads will continue to be drawn in their paused state.
        See Also:
        resumeThreads(), pauseAndClearThreads()

      • pauseAndClearThreads

        public void pauseAndClearThreads()
        Pauses all threads and clears them from being drawn.
        See Also:
        resumeThreads(), pauseThreads()

      • resumeThread

        public void resumeThread​(PThread... thread)
        Resumes a given thread or threads (varargs).
        Parameters:
        thread - The thread (or threads) to resume
        See Also:
        pauseThread(PThread...)

      • stopThread

        public void stopThread​(PThread... thread)
        Stops a given thread or threads (varargs) and removes it from the thread manager (cannot be resumed).
        Parameters:
        thread - The thread (or threads) to stop indefinitely

      • stopThreads

        public void stopThreads()
        Stops all threads (even if they are paused) and removes them from the thread manager, effectively resetting the thread manager.

      • draw

        public void draw()
        Draws the threads' PGraphics into the parent PApplet. This method should be called within the parent PApplet's draw() loop -- alternatively, see bindDraw().

      • unlinkComputeDraw

        public void unlinkComputeDraw()
        Advanced: By default, each thread's draw() and calc() methods are called sequentially within the thread. But what if a given thread is severely draw-call bound? When this function is called, all threads' (both existing and future) calc() method will be called as part of the thread manager's draw() method and not within the threads. In other words, draw-intensive sketches (threads) will not slow down the processing/calculation speed of a thread.

      • relinkComputeDraw

        public void relinkComputeDraw()
        Instructs the thread manager that both existing and future threads' draw() and calc() methods are to be called sequentially (default behaviour).
        See Also:
        unlinkComputeDraw()

      • getThreadCount

        public int getThreadCount()
        Returns the count of the threads (both paused and running) managed by this thread manager.
        Returns:
        thread count

      • getAverageDrawFPS

        public float getAverageDrawFPS()
        First enables timing collection for each thread, then returns the average FPS of running threads' draw() loops.
        Returns:
        mean draw() FPS of all threads
        See Also:
        getAverageCalcFPS()

      • getAverageCalcFPS

        public float getAverageCalcFPS()
        First enables timing collection for each thread, then returns the average FPS of running threads' calc() loops.
        Returns:
        mean calc() FPS of all threads
        See Also:
        getAverageDrawFPS()

      • isRunning

        public boolean isRunning()
        Is the thread manager running any threads? If pauseThreads() has been called, this method will return false.
        Returns:
        running status

      • bindDraw

        public void bindDraw()
        Binds the draw() method of this thread manager to the end of the draw method of the parent PApplet, so you don't need to manually include a call to myManger.draw() in the PApplet's draw() method. By default, the thread manager is not bound to the parent PApplet -- this method must be called to set it up.
        See Also:
        unBindDraw()

      • unBindDraw

        public void unBindDraw()
        Unbinds the draw() method of this thread manager from the end of the draw method of the parent PApplet, so draw() must be called manually.
        See Also:
        bindDraw()

      • dispose

        public void dispose()
        This method is bound to the parent PApplet, so that the threads are terminated properly when the sketch is closed. You do not need to call this method manually.