Package org.terracotta.utilities.test.net

Class PortManager

java.lang.Object
org.terracotta.utilities.test.net.PortManager
public class PortManager extends Object
Manages TCP port reservation/de-reservation while attempting to avoid intra- and extra-JVM interference.

The port manager maintains two levels of reservation -- intra-JVM using an internal BitSet and inter-JVM using locks against a RandomAccessFile allocated in a system-wide, world-writable, system-dependent location. To avoid reservation/use races, ephemeral ports are not used.

All users of PortManager in a JVM must use the same PortManager instance to ensure proper intra-JVM reservations.

By default, release of an assigned port back to PortManager (via PortManager.PortRef.close() or garbage collection of a weakly-reachable PortRef instance) performs a check that the port is actually unused. This involves querying both the in-use ports and active processes on the system and, on some systems, could be a time-consuming activity. While the check is intended to identify "outside" interference with ports assigned by PortManager, it is possible to disable this check by setting the "org.terracotta.disablePortReleaseCheck" property or "DISABLE_PORT_RELEASE_CHECK" environment variable to true. The property value is examined each time the release check is performed so the check may be disabled for some tests and left enabled for others; the environment variable is only examined when the PortManger class is loaded.

  • Field Details

    • DISABLE_PORT_RELEASE_CHECK_PROPERTY

      public static final String DISABLE_PORT_RELEASE_CHECK_PROPERTY
      Property checked for disabling the port release check performed at the time a port obtained from PortManager is returned to PortManager.
      See Also:

    • DISABLE_PORT_RELEASE_CHECK_ENV_VARIABLE

      public static final String DISABLE_PORT_RELEASE_CHECK_ENV_VARIABLE
      Environment variable checked for disabling the port release check performed at the time a port obtained from PortManager is returned to PortManger.
      See Also:

    • LOGGER

      private static final org.slf4j.Logger LOGGER

    • DISABLE_PORT_RELEASE_CHECK

      private static final boolean DISABLE_PORT_RELEASE_CHECK
      Reflects the value of the "DISABLE_PORT_RELEASE_CHECK" environment variable. If the environment variable is set to a case-insensitive value of true, the port release check will be disabled.

      The value of the environment variable is only checked when this class is loaded; changes to the environment variable after this class is loaded are not detected.

    • INSTANCE

      private static final PortManager INSTANCE

    • MAXIMUM_PORT_NUMBER

      private static final int MAXIMUM_PORT_NUMBER
      See Also:

    • MINIMUM_ASSIGNABLE_PORT_COUNT

      private static final int MINIMUM_ASSIGNABLE_PORT_COUNT
      See Also:

    • LOCALHOST

      private static final InetAddress LOCALHOST

    • rnd

      private final Random rnd

    • restrictedPorts

      private final BitSet restrictedPorts
      Marks the ports which cannot be allocated by this class. A true bit in this BitSet indicates a non-reservable (restricted) port.

    • portMap

      private final BitSet portMap
      Port allocation map. A zero bit represents an available port.

    • allocatedPorts

      private final Map<Integer,PortManager.AllocatedPort> allocatedPorts
      References to outstanding PortManager.PortRef instances.

    • dereferencedPorts

      private final ReferenceQueue<PortManager.PortRef> dereferencedPorts
      A ReferenceQueue accepting PortManager.PortRef instances no longer held by the reserving party.

    • systemLevelLocker

      private final SystemLevelLocker systemLevelLocker
      Manages port reservations at a system level using file locks.

    • assignablePortCount

      private final int assignablePortCount
      The number of non-reserved ports. This is the absolute upper limit of the number of ports that can possibly be assigned.

  • Constructor Details

    • PortManager

      private PortManager()
      Creates a PortManager instance primed for reserving ports outside of current system's the ephemeral port range.

  • Method Details

    • getInstance

      public static PortManager getInstance()
      Gets the singleton instance of PortManager to use in a JVM.
      Returns:
      the singleton PortManager instance

    • isReservablePort

      public boolean isReservablePort(int port)
      Indicates if the designated port is in the range of ports that may be allocated by this class. If the designated port is in the range of ports that may be allocated, the reserve(int) method may be used to attempt to allocate the port. The port may also be returned from the reservePort() and reservePorts(int) methods.
      Parameters:
      port - the port number to test
      Returns:
      true if port may be reserved using reserve(int); false if port is not a reservable port. A true result is not an indication that port is currently available to be reserved.
      Throws:
      IllegalArgumentException - if port is not between 0 and 65535 (inclusive)

    • getPortRef

      public Optional<PortManager.PortRef> getPortRef(int port)
      Gets the active PortManager.PortRef instance for the designated port.

      This method returns a reference to the most recent PortRef created for the designated port if the PortRef is both strongly reachable and not closed. The result of this method may be immediately stale -- the PortRef may be closed between the time the PortRef is checked and the reference returned to the called.

      Parameters:
      port - the port number for which the PortRef is returned
      Returns:
      an Optional of the PortRef for port if the PortRef is both strongly reachable and not closed; Optional.empty if the PortRef for port is either not strongly reachable or closed
      Throws:
      IllegalArgumentException - if port is not between 0 and 65535 (inclusive) or is not a reservable port

    • reserve

      public Optional<PortManager.PortRef> reserve(int port)
      Attempts to reserve the specified port.

      The PortManager.PortRef.close() method should be called when the port is no longer needed. However, the returned PortRef instance must strongly-referenced as long as the port is required -- once the PortRef instance becomes weakly-referenced, the port reservation may be released.

      Parameters:
      port - the port number to reserve
      Returns:
      an Optional containing the PortManager.PortRef if the port was successfully reserved; Optional.empty if the port could not be reserved
      Throws:
      IllegalArgumentException - if port is not between 0 and 65535 (inclusive) or is not a reservable port
      IllegalStateException - if reservation fails due to an error

    • reservePorts

      public List<PortManager.PortRef> reservePorts(int portCount)
      Reserves the specified number of ports returning a list of PortManager.PortRef instances for those reserved.

      The PortManager.PortRef.close() method should be called on each port when no longer needed. However, each returned PortRef instance must strongly-referenced as long as the port is required -- once the PortRef instance becomes weakly-referenced, the port reservation may be released.

      Parameters:
      portCount - the number of ports to reserve
      Returns:
      the list of PortRef instances for the reserved ports; the ports are not assigned sequentially
      Throws:
      IllegalArgumentException - if portCount is less than 1 or greater than the number of reservable ports
      IllegalStateException - if the reservable ports are exhausted or reservation fails due to an error

    • reservePort

      public PortManager.PortRef reservePort()
      Reserve a single, randomly selected port.

      The PortManager.PortRef.close() method should be called on the port when no longer needed. However, the returned PortRef instance must strongly-referenced as long as the port is required -- once the PortRef instance becomes weakly-referenced, the port reservation may be released.

      Returns:
      a PortRef instance identifying the reserved port
      Throws:
      IllegalStateException - if the reservable ports are exhausted or reservation fails due to an error

    • cleanReleasedPorts

      private void cleanReleasedPorts()
      Releases PortRef instances no longer strongly held. These PortRef instances are considered available for reuse.

    • reserveInternal

      private PortManager.PortRef reserveInternal(int candidatePort)
      Reserve and vet the specified candidate port.
      Parameters:
      candidatePort - the port to vet and reserve
      Returns:
      a new PortRef instance is the reservation was successful; null otherwise
      Throws:
      IllegalStateException - if port reservation fails due to a locking error

    • release

      private void release(int port, Set<PortManager.PortRef.CloseOption> options)

    • refusesConnect

      private boolean refusesConnect(int port)
      Determines if a client connection to the specified port is accepted or refused.

      On some versions of Windows, a port can pass the server bind test and still not really be free. According to issue MNK-5621, some Windows services, like Remote Desktop (RDP) don't establish an open listener but do respond to connection requests on their assigned port(s). A "failure to connect" is necessary to determine if the port is actually available. (This check presumes firewall rules aren't responsible for dropping the connection request -- not much we can do about that.)

      Parameters:
      port - the port to test
      Returns:
      true if the port is available (free); false otherwise
      See Also:

    • diagnosticReleaseCheck

      private void diagnosticReleaseCheck(int port, Set<PortManager.PortRef.CloseOption> options)
      Checks that the port being released is actually free and emits a detailed log message if not. This check is not performed if the "org.terracotta.disablePortReleaseCheck" system property or the "DISABLE_PORT_RELEASE_CHECK" environment variable is set to true.
      Parameters:
      port - the port to check
      options - the set of PortManager.PortRef.CloseOption members used to influence the release check

    • disablePortReleaseCheck

      private static void disablePortReleaseCheck()

    • emitInstanceNotification

      private static void emitInstanceNotification(String use)

    • combine

      private static <T, U> BiConsumer<T,U> combine(BiConsumer<T,U> a, BiConsumer<T,U> b)
      Combines BiConsumer instances to run in reverse sequence.
      Parameters:
      a - the second BiConsumer to run
      b - the first BiConsumer to run
      Returns:
      a new BiConsumer running b then a