Package org.spiderwiz.zutils

Class ZBuffer<T>

java.lang.Object
org.spiderwiz.zutils.ZBuffer<T>
Type Parameters:
T - type of elements managed by the buffer.
All Implemented Interfaces:
Runnable
public class ZBuffer<T>
extends Object
implements Runnable
Manages the processing of a queue of elements.

The class uses a LinkedList to hold a queue of elements and manage their processing. Typically the user of the class uses add() to push elements to the head of the buffer, and the buffer itself, running on its own thread(s), pulls the elements from its bottom and dispatches them for processing using a ZDispenser object, which is provided to the class constructor. A buffer that operates this way is a self-dispensing buffer. The mechanism of this buffer shall be activated by calling execute(). Alternatively, buffers can be user-dispensed, in which case the user calls pull() to pull elements from the bottom of the buffer and process them.

There is a constructor version that lets you specify the number of threads that are allocated for processing buffer items. If the other constructor is used and this is not a user-dispensed buffer then one thread is allocated.

You can call addUrgent() to push an urgent element. That would place the element at the bottom of the buffer (on top of previous urgent elements).

Other features include setting timeout for pulling from an empty buffer by calling setTimeout(), setting buffer capacity by calling setMaxCapacity(), requesting to empty the buffer when it is full with setEmptyOnFull(), requesting that when adding an item to a full buffer the bottom element of the buffer will be discarded without processing by calling setDiscardOnFull() and marking the buffer as lossless by calling setLossless() in which case pushing elements to the buffer when it is full would block the calling thread until some space is freed.

You can also assign a backup file to the buffer, in which case when the buffer is full excess items will be stored in the given disc file and retrieved for pushing into the main buffer when space is freed. To do that activate the buffer with execute(filename). If you use this option, the buffer's elements will be serialized to the file through their Object.toString() method, and, unless the element type is String, you should override fromString() to provide deserialization code.

See Also:
ZDispenser

  • Constructor Summary

    Constructors 
    Constructor Description
    ZBuffer​(ZDispenser<T> dispenser)
    Constructs a single-thread buffer.
    ZBuffer​(ZDispenser<T> dispenser, int threads)
    Constructs a buffer.

  • Method Summary

    Modifier and Type Method Description
    boolean add​(T o)
    Appends an element to the top of the buffer.
    boolean addUrgent​(T o)
    Inserts an urgent element to the buffer.
    void cleanup​(boolean flush)
    Cleans up buffer resources.
    void execute()
    Activates the buffer.
    void execute​(String backupFile)
    Activates the buffer with a backup file.
    protected T fromString​(String line)
    Deserializes a string into an object of the type managed by the buffer.
    boolean isEmpty()
    Returns true if the buffer is empty.
    T pull​(boolean wait)
    Retrieves and removes the bottom element of this buffer (head of the queue).
    void run()
    Implementation of Runnable.run().
    void setDiscardOnFull​(boolean discardOnFull)
    Sets discard-on-full value.
    void setEmptyOnFull​(boolean emptyOnFull)
    Sets empty-on-full value.
    void setLossless​(boolean lossless)
    Sets lossless value.
    void setMaxCapacity​(int maxCapacity)
    Sets the maximum number of elements in the buffer.
    void setTimeout​(long timeout)
    Sets the maximum time in milliseconds to wait for data when pulling from an empty buffer.

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • ZBuffer

      public ZBuffer​(ZDispenser<T> dispenser)
      Constructs a single-thread buffer.

      Constructs a single-thread buffer with a given dispenser. If dispenser is not null a self-disposing buffer is constructed. If it is null the constructed buffer is user-dispensed, i.e. the user needs to call pull() to process buffer elements.

      Parameters:
      dispenser - the buffer's dispenser, or null if this is a user-dispensed buffer.

    • ZBuffer

      public ZBuffer​(ZDispenser<T> dispenser, int threads)
      Constructs a buffer.

      Constructs a buffer with a given dispenser. If dispenser is not null a self-disposing buffer is constructed. If it is null the constructed buffer is user-dispensed, i.e. the user needs to call pull() to process buffer elements.

      The threads parameter determines the number of the threads to spawn for processing buffer items. If negative, as many as available CPUs on this machine will be spawned. If Zero, this is not a user-dispensed buffer. Note that a multi-thread buffer cannot guarantee processing order.

      Parameters:
      dispenser - the buffer's dispenser, or null if this is a user-dispensed buffer.
      threads - the number of the threads to spawn for processing buffer items. If negative, as many as available CPUs on this machine will be spawned. If Zero, this is not a user-dispensed buffer.

  • Method Details

    • setTimeout

      public final void setTimeout​(long timeout)
      Sets the maximum time in milliseconds to wait for data when pulling from an empty buffer.

      Sets the maximum time in milliseconds a pull operation will wait on an empty buffer until an element is available. If timeout is zero, the operation will wait unlimited until an element is available or the buffer operation is aborted by cleanup().

      If timeout is a positive value and a pull operation expires while the buffer is still empty, the pull result will be null.

      Parameters:
      timeout - the maximum time in milliseconds to wait for data when pulling from an empty buffer, or zero if waiting is unlimited.

    • setMaxCapacity

      public final void setMaxCapacity​(int maxCapacity)
      Sets the maximum number of elements in the buffer.

      The buffer is considered full when the defined maximum capacity is reached. The default value is 60000.

      Parameters:
      maxCapacity - maximum number of elements in the buffer.

    • setDiscardOnFull

      public final void setDiscardOnFull​(boolean discardOnFull)
      Sets discard-on-full value.

      When discard-on-full is set to true, adding an element to a full buffer will cause the element at the bottom of the buffer to be discarded without processing in order to make room for the new element pushed on top. The default is false.

      Parameters:
      discardOnFull - true to set discard-on-full on, false to set it off.

    • setEmptyOnFull

      public final void setEmptyOnFull​(boolean emptyOnFull)
      Sets empty-on-full value.

      When empty-on-full is set to true, adding an element to a full buffer will cause the entire buffer to be emptied, except of the urgent elements, without processing. The added element will be placed in the empty buffer. This is the default.

      Parameters:
      emptyOnFull - true to set empty-on-full on (the default), false to set it off.

    • setLossless

      public final void setLossless​(boolean lossless)
      Sets lossless value.

      When lossless is set to true, adding elements to the buffer when it is full would block the calling thread until some space is freed. The default is false.

      Parameters:
      lossless - true to set lossless on, false to set it off.

    • execute

      public void execute()
      Activates the buffer.

      This method must be called if the buffer is self-dispensing. It has no effect if no dispenser was provided to the class constructor.

    • execute

      public final void execute​(String backupFile)
      Activates the buffer with a backup file.

      Activate the buffer with this method if you want to specify a backup file to store excess elements when the buffer is full. When buffer space is freed, elements will be retrieved from the file and added to the buffer.

      This method also activates a self-dispensing buffer. If no dispenser was provided to the class constructor, the self-dispensing mechanism will not be activated but the backup file will still be set.

      Parameters:
      backupFile - backup file pathname.

    • add

      public final boolean add​(T o)
      Appends an element to the top of the buffer.

      Appends an element to the top of the buffer, i.e. to the tail of the queue. If the buffer is full the result depends on the various settings of the buffer, as follow:

      • If lossless is set to true the calling thread is blocked until buffer space for one element is freed.
      • if empty-on-full is set to true (the default) the buffer will be cleared entirely, except of the urgent elements, before the new element is placed in it.
      • if discard-on-full is set to true the element at the bottom of the buffer (head of the queue) will be removed and discarded without being processed.
      • if a backup file name is supplied in the call to execute() the new element will be stored in the file, to be retrieved later when the buffer has space.
      • if none of the above is set, the element will not be appended to the buffer and the method will return false.
      Parameters:
      o - element to be appended to this buffer.
      Returns:
      true if any only if the element was appended to the buffer.
      See Also:
      addUrgent()

    • addUrgent

      public final boolean addUrgent​(T o)
      Inserts an urgent element to the buffer.

      This method inserts an urgent element at the bottom of the buffer (head of the queue) on top of previously inserted urgent elements. This causes the processing of urgent elements before other elements are processed.

      See add() for what happens if the buffer is full.

      Parameters:
      o - element to be inserted to this buffer.
      Returns:
      true if any only if the element was inserted into the buffer.
      See Also:
      add()

    • pull

      public T pull​(boolean wait)
      Retrieves and removes the bottom element of this buffer (head of the queue).

      Used if the buffer is user-dispensed. Self-dispensed buffers process the queue by themselves and therefore this method shall not be used on them.

      Parameters:
      wait - if true and the buffer is empty, wait the set time until an element is available.
      Returns:
      the bottom element of the buffer or null if the buffer is empty and wait time has expired.

    • isEmpty

      public boolean isEmpty()
      Returns true if the buffer is empty.
      Returns:
      true if and only if the buffer is empty.

    • fromString

      protected T fromString​(String line)
      Deserializes a string into an object of the type managed by the buffer.

      This method is used if the buffer is activated with a backup file. In that case you need to override this method to provide code for deserializing file records, kept as strings, into objects of the type managed by the buffer. There is no need to override the method if the element type of the buffer is String.

      Parameters:
      line - a string representing a serialized buffer's element.
      Returns:
      an object of the type managed by the buffer.

    • cleanup

      public void cleanup​(boolean flush)
      Cleans up buffer resources.

      Call this method when you do not need the buffer any more. If flush is true the caller thread will be blocked until all remaining buffer elements are dispensed and processed.

      Parameters:
      flush - true if all remaining buffer elements shall be dispensed and processed.

    • run

      public final void run()
      Implementation of Runnable.run().

      Do not call or overload.

      Specified by:
      run in interface Runnable