Package org.jcsp.net2

Class NetBarrier

  • All Implemented Interfaces:
    java.io.Serializable, Networked

    public final class NetBarrier
    extends Barrier
    implements Networked
    This class is a networked implementation of the standard JCSP Barrier.

    The NetBarrier is a networked version of the JCSP Barrier, a synchronization primitive similar to the standard event in CSP. The networked implementation follows the standard interface for a local Barrier, with the addition of the interface defining a networked construct. Internally, the two constructs behave differently due to the distributed nature of the NetBarrier.

    Client and Server Ends

    Unlike a normal Barrier, a NetBarrier has two types, based on whether the Barrier is the hosting end or an attached, synchronizing end. These are differentiated between as server and client ends. The server end, like the input end of a networked channel, will be declared first. The location of this server end can then be used to connect a number of client ends to. The server end can declare an initial number of expected client ends, which it waits for enrolls from before beginning any sync operations. This value can be set to 0 if need be. Each end of a barrier must also declare the number of local syncing processes, creating a two tier construct:

    Process ---> NetBarrier (client) ---> NetBarrier (server)

    Creating NetBarriers

    To create a NetBarrier, a similar method is used as a networked channel. A Barrier Name Server is provided for declaring named barriers, or the NetBarrierEnd factory can be used. First, creation of a sever end:

    int locallyEnrolled = 5;
    int remoteEnrolled = 1;
    NetBarrier bar = NetBarrierEnd.netBarrier(locallyEnrolled, remoteEnrolled);

    A client end requires the location of this barrier to allow creation:

    NetBarrierLocation loc;
    int locallyEnrolled = 5;
    NetBarrier bar = NetBarrierEnd.netBarrier(loc, locallyEnrolled);

    These barriers can then be used as normal.

    IMPLMENTATION NOTE

    To save on resources, a NetBarrier does not have an internal process controlling it (although other implementations may decide to do this). Because of this, the declaring (server) end of the barrier must always have at least one process enrolled with it to ensure that the SYNC operation occurs. If there is a danger that the enrolled processes on the server node will become 0, it is safer to define a process that is only responsible for SYNCing with the barrier. This minor overhead in certain circumstances is seen as a better approach than all NetBarriers being a process within JCSP, where processes are expensive in resources.

    public void run() {
    while (true) {
    bar.sync(); }}

    See Also:
    Barrier, Serialized Form
    • Field Summary

      Fields 
      Modifier and Type Field Description
      private BarrierData data
      The data structure representing this NetBarrier object
      private AltingChannelInput in
      The input channel into this NetBarrier from the Links
      private int initialNetEnrollCountdown
      The number of initial network enrolls that this barrier must wait for.
      private BarrierData localBar
      Used by a locally connected barrier to allow it to check the state prior to sending the SYNC.
      private int localCountDown
      The number of local processes still to SYNC
      private int localEnrolled
      The number of locally connected processes
      private NetBarrierLocation localLocation
      The local location of this NetBarrier
      private boolean locallyConnected
      Flag used to determine if the NetBarrier is connected to a server end on the same Node
      private java.lang.Object lock
      The exclusive access lock for syncing, etc.
      private int netCountDown
      The number of networked processes still to SYNC
      private int netEnrolled
      The number of remote connected processes
      private boolean performNetSync
      A flag used to signify that a waking process should perform a network sync when released
      private NetBarrierLocation remoteLocation
      The location that this NetBarrier is connected to
      private static long serialVersionUID
      The SUID for this object.
      private ChannelOutput toLinkTX
      The connection to the Link that the client end communicates with
      private java.util.LinkedList waitingEnds
      A queue of waiting network ends waiting for a SYNC message
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      (package private) static NetBarrier create​(int localEnroll, int remoteEnroll)
      Static factory method used to create a server end of a NetBarrier
      (package private) static NetBarrier create​(int localEnroll, int remoteEnroll, int barrierIndex)
      Static factory method for creating a new NetBarrier with a given index
      (package private) static NetBarrier create​(NetBarrierLocation loc, int localEnroll)
      Static factory method for creating a client end of a NetBarrier
      void destroy()
      Destroys the Barrier
      void enroll()
      Enrolls locally with the Barrier
      (package private) NetBarrierLocation getLocalLocation()
      Gets the local location of the barrier
      NetLocation getLocation()
      Returns the location of this barrier
      void reset​(int numToEnroll)
      Resets the number of locally enrolled processes.
      void resign()
      Resigns an local process from the barrier
      void sync()
      Performs a SYNC operation with the Barrier throws JCSPNetworkException Thrown if something goes wrong in the underlying architecture
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • serialVersionUID

        private static final long serialVersionUID
        The SUID for this object. Shouldn't really need it. Barrier should not be serializable.
        See Also:
        Constant Field Values
      • data

        private final BarrierData data
        The data structure representing this NetBarrier object
      • remoteLocation

        private final NetBarrierLocation remoteLocation
        The location that this NetBarrier is connected to
      • localLocation

        private final NetBarrierLocation localLocation
        The local location of this NetBarrier
      • localEnrolled

        private int localEnrolled
        The number of locally connected processes
      • localCountDown

        private int localCountDown
        The number of local processes still to SYNC
      • netEnrolled

        private int netEnrolled
        The number of remote connected processes
      • netCountDown

        private int netCountDown
        The number of networked processes still to SYNC
      • locallyConnected

        private boolean locallyConnected
        Flag used to determine if the NetBarrier is connected to a server end on the same Node
      • waitingEnds

        private final java.util.LinkedList waitingEnds
        A queue of waiting network ends waiting for a SYNC message
      • initialNetEnrollCountdown

        private int initialNetEnrollCountdown
        The number of initial network enrolls that this barrier must wait for.
      • toLinkTX

        private ChannelOutput toLinkTX
        The connection to the Link that the client end communicates with
      • localBar

        private BarrierData localBar
        Used by a locally connected barrier to allow it to check the state prior to sending the SYNC.
      • in

        private final AltingChannelInput in
        The input channel into this NetBarrier from the Links
      • lock

        private final java.lang.Object lock
        The exclusive access lock for syncing, etc.
      • performNetSync

        private boolean performNetSync
        A flag used to signify that a waking process should perform a network sync when released
    • Constructor Detail

      • NetBarrier

        private NetBarrier​(BarrierData barData,
                           int numToEnroll,
                           int netNumToEnroll,
                           NetBarrierLocation serverLocation,
                           AltingChannelInput inToBar,
                           ChannelOutput toLink)
                    throws java.lang.IllegalArgumentException
        The constructor for a NetBarrier
        Parameters:
        barData - The data structure defining the Barrier
        numToEnroll - The number of local processes to enroll
        netNumToEnroll - The number of network processes that will enroll
        serverLocation - The location of the server end of the NetBarrier
        inToBar - The channel into the NetBarrier from the Link
        toLink - The channel connecting the client end of a NetBarrierer to its Link
        Throws:
        java.lang.IllegalArgumentException - Thrown if the number of local enrolled processes is less than 1, or remote enrolled is less than 0
    • Method Detail

      • create

        static NetBarrier create​(int localEnroll,
                                 int remoteEnroll)
                          throws java.lang.IllegalArgumentException
        Static factory method used to create a server end of a NetBarrier
        Parameters:
        localEnroll - The number of locally enrolled processes
        remoteEnroll - The number of remote processes to wait for enrolls from
        Returns:
        A new NetBarrier
        Throws:
        java.lang.IllegalArgumentException - Thrown if the number of enrolled processes is outside the defined ranges
      • create

        static NetBarrier create​(int localEnroll,
                                 int remoteEnroll,
                                 int barrierIndex)
                          throws java.lang.IllegalArgumentException
        Static factory method for creating a new NetBarrier with a given index
        Parameters:
        localEnroll - The number of locally enrolled processes
        remoteEnroll - The number of remote processes to wait for enrolls from
        barrierIndex - The index to create the barrier with
        Returns:
        A new NetBarrier
        Throws:
        java.lang.IllegalArgumentException - Thrown if the any of the arguments are outside the desired ranges.
      • create

        static NetBarrier create​(NetBarrierLocation loc,
                                 int localEnroll)
                          throws JCSPNetworkException,
                                 java.lang.IllegalArgumentException
        Static factory method for creating a client end of a NetBarrier
        Parameters:
        loc - The location of the server end of the connection
        localEnroll - The number of locally enrolled processes
        Returns:
        A new NetBarrier client end
        Throws:
        JCSPNetworkException - Thrown if something goes wrong in the underlying architecture
        java.lang.IllegalArgumentException - Thrown if local enrolled is less than 1
      • reset

        public void reset​(int numToEnroll)
        Resets the number of locally enrolled processes. A dangerous operation.
        Overrides:
        reset in class Barrier
        Parameters:
        numToEnroll - The number of processes to reset the enrolled to.
      • sync

        public void sync()
                  throws JCSPNetworkException
        Performs a SYNC operation with the Barrier throws JCSPNetworkException Thrown if something goes wrong in the underlying architecture
        Overrides:
        sync in class Barrier
        Throws:
        JCSPNetworkException - Thrown if something goes wrong in the underlying architecture
      • getLocation

        public NetLocation getLocation()
        Returns the location of this barrier
        Specified by:
        getLocation in interface Networked
        Returns:
        The location of this channel
      • getLocalLocation

        NetBarrierLocation getLocalLocation()
        Gets the local location of the barrier
        Returns:
        The local location of the barrier