Add durations to connection pool events

JAVA-5076

Author: stIncMale

driver-core/src/main/com/mongodb/ConnectionString.java

@@ -19,6 +19,7 @@
 import com.mongodb.connection.ClusterSettings;
 import com.mongodb.connection.ConnectionPoolSettings;
 import com.mongodb.connection.SocketSettings;
+import com.mongodb.event.ConnectionCreatedEvent;
 import com.mongodb.internal.diagnostics.logging.Logger;
 import com.mongodb.internal.diagnostics.logging.Loggers;
 import com.mongodb.internal.dns.DefaultDnsResolver;
@@ -132,8 +133,9 @@
  * <ul>
  * <li>{@code maxPoolSize=n}: The maximum number of connections in the connection pool.</li>
  * <li>{@code minPoolSize=n}: The minimum number of connections in the connection pool.</li>
- * <li>{@code waitQueueTimeoutMS=ms}: The maximum wait time in milliseconds that a thread may wait for a connection to
- * become available.</li>
+ * <li>{@code waitQueueTimeoutMS=ms}: The maximum duration to wait for either an available connection
+ * (limited by {@link #getMaxConnectionPoolSize()}),
+ * or a {@linkplain ConnectionCreatedEvent newly created connection} (limited by {@link #getMaxConnecting()}).</li>
  * <li>{@code maxConnecting=n}: The maximum number of connections a pool may be establishing concurrently.</li>
  * </ul>
  * <p>Write concern configuration:</p>
@@ -1366,15 +1368,18 @@ public Integer getMinConnectionPoolSize() {
     /**
      * Gets the maximum connection pool size specified in the connection string.
      * @return the maximum connection pool size
+     * @see ConnectionPoolSettings#getMaxSize()
      */
     @Nullable
     public Integer getMaxConnectionPoolSize() {
         return maxConnectionPoolSize;
     }
 
     /**
-     * Gets the maximum wait time of a thread waiting for a connection specified in the connection string.
-     * @return the maximum wait time of a thread waiting for a connection
+     * The maximum duration to wait for either an available connection (limited by {@link #getMaxConnectionPoolSize()}),
+     * or a {@linkplain ConnectionCreatedEvent newly created connection} (limited by {@link #getMaxConnecting()}).
+     * @return the maximum wait time when waiting for a connection
+     * @see ConnectionPoolSettings#getMaxWaitTime(TimeUnit)
      */
     @Nullable
     public Integer getMaxWaitTime() {

driver-core/src/main/com/mongodb/connection/ConnectionPoolSettings.java

@@ -19,6 +19,7 @@
 import com.mongodb.ConnectionString;
 import com.mongodb.annotations.Immutable;
 import com.mongodb.annotations.NotThreadSafe;
+import com.mongodb.event.ConnectionCheckedOutEvent;
 import com.mongodb.event.ConnectionCreatedEvent;
 import com.mongodb.event.ConnectionPoolListener;
 import com.mongodb.event.ConnectionReadyEvent;
@@ -112,13 +113,15 @@ public Builder applySettings(final ConnectionPoolSettings connectionPoolSettings
         }
 
         /**
-         * <p>The maximum number of connections allowed. Those connections will be kept in the pool when idle. Once the pool is exhausted,
-         * any operation requiring a connection will block waiting for an available connection.</p>
+         * <p>The maximum number of connections allowed. Those connections will be kept in the pool when idle. Once the pool is exhausted, any
+         * operation requiring a connection will block waiting for an available connection.
+         * The duration of such waiting is affected by the {@link #getMaxWaitTime(TimeUnit)} setting.</p>
          *
          * <p>Default is 100.</p>
          *
          * @param maxSize the maximum number of connections in the pool; if 0, then there is no limit.
          * @return this
+         * @see #getMaxSize()
          */
         public Builder maxSize(final int maxSize) {
             this.maxSize = maxSize;
@@ -140,13 +143,19 @@ public Builder minSize(final int minSize) {
         }
 
         /**
-         * <p>The maximum time that a thread may wait for a connection to become available.</p>
+         * <p>
+         * The maximum duration to wait for either an available connection (limited by {@link #getMaxSize()}),
+         * or a {@linkplain ConnectionCreatedEvent newly created connection} (limited by {@link #getMaxConnecting()}).
+         * Note that the latter then has to be {@linkplain ConnectionReadyEvent established}
+         * before {@link ConnectionCheckedOutEvent checking out is completed}.
+         * Establishment of a connection is not controlled by this setting.</p>
          *
          * <p>Default is 2 minutes. A value of 0 means that it will not wait.  A negative value means it will wait indefinitely.</p>
          *
          * @param maxWaitTime the maximum amount of time to wait
          * @param timeUnit    the TimeUnit for this wait period
          * @return this
+         * @see #getMaxWaitTime(TimeUnit)
          */
         public Builder maxWaitTime(final long maxWaitTime, final TimeUnit timeUnit) {
             this.maxWaitTimeMS = MILLISECONDS.convert(maxWaitTime, timeUnit);
@@ -293,11 +302,14 @@ public Builder applyConnectionString(final ConnectionString connectionString) {
 
     /**
      * <p>The maximum number of connections allowed. Those connections will be kept in the pool when idle. Once the pool is exhausted, any
-     * operation requiring a connection will block waiting for an available connection.</p>
+     * operation requiring a connection will block waiting for an available connection.
+     * The duration of such waiting is affected by the {@link #getMaxWaitTime(TimeUnit)} setting.</p>
      *
      * <p>Default is 100.</p>
      *
      * @return the maximum number of connections in the pool; if 0, then there is no limit.
+     * @see Builder#maxSize(int)
+     * @see ConnectionString#getMaxConnectionPoolSize()
      */
     public int getMaxSize() {
         return maxSize;
@@ -316,12 +328,19 @@ public int getMinSize() {
     }
 
     /**
-     * <p>The maximum time that a thread may wait for a connection to become available.</p>
+     * <p>
+     * The maximum duration to wait for either an available connection (limited by {@link #getMaxSize()}),
+     * or a {@linkplain ConnectionCreatedEvent newly created connection} (limited by {@link #getMaxConnecting()}).
+     * Note that the latter then has to be {@linkplain ConnectionReadyEvent established}
+     * before {@link ConnectionCheckedOutEvent checking out is completed}.
+     * Establishment of a connection is not controlled by this setting.</p>
      *
      * <p>Default is 2 minutes. A value of 0 means that it will not wait.  A negative value means it will wait indefinitely.</p>
      *
      * @param timeUnit the TimeUnit for this wait period
      * @return the maximum amount of time to wait in the given TimeUnits
+     * @see Builder#maxWaitTime(long, TimeUnit)
+     * @see ConnectionString#getMaxWaitTime()
      */
     public long getMaxWaitTime(final TimeUnit timeUnit) {
         return timeUnit.convert(maxWaitTimeMS, MILLISECONDS);
@@ -384,10 +403,14 @@ public List<ConnectionPoolListener> getConnectionPoolListeners() {
      * Establishment of a connection is a part of its life cycle
      * starting after a {@link ConnectionCreatedEvent} and ending before a {@link ConnectionReadyEvent}.
      * <p>
+     * This limit may cause waiting when checking out a connection.
+     * The duration of such waiting is affected by the {@link #getMaxWaitTime(TimeUnit)} setting.</p>
+     * <p>
      * Default is 2.</p>
      *
      * @return The maximum number of connections a pool may be establishing concurrently.
      * @see Builder#maxConnecting(int)
+     * @see ConnectionString#getMaxConnecting()
      * @since 4.4
      */
     public int getMaxConnecting() {

driver-core/src/main/com/mongodb/event/ConnectionCheckOutFailedEvent.java

@@ -16,8 +16,12 @@
 
 package com.mongodb.event;
 
+import com.mongodb.connection.ConnectionPoolSettings;
 import com.mongodb.connection.ServerId;
 
+import java.util.concurrent.TimeUnit;
+
+import static com.mongodb.assertions.Assertions.isTrueArgument;
 import static com.mongodb.assertions.Assertions.notNull;
 
 /**
@@ -54,8 +58,25 @@ public enum Reason {
 
     private final ServerId serverId;
     private final long operationId;
-
     private final Reason reason;
+    private final long elapsedTimeNanos;
+
+    /**
+     * Constructs an instance.
+     *
+     * @param serverId The server ID. See {@link #getServerId()}.
+     * @param operationId The operation ID. See {@link #getOperationId()}.
+     * @param reason The reason the connection check out failed. See {@link #getReason()}.
+     * @param elapsedTimeNanos The time it took while trying to check out the connection. See {@link #getElapsedTime(TimeUnit)}.
+     * @since VAKOTODO
+     */
+    public ConnectionCheckOutFailedEvent(final ServerId serverId, final long operationId, final Reason reason, final long elapsedTimeNanos) {
+        this.serverId = notNull("serverId", serverId);
+        this.operationId = operationId;
+        this.reason = notNull("reason", reason);
+        isTrueArgument("waited time is not negative", elapsedTimeNanos >= 0);
+        this.elapsedTimeNanos = elapsedTimeNanos;
+    }
 
     /**
      * Construct an instance
@@ -64,11 +85,12 @@ public enum Reason {
      * @param operationId the operation id
      * @param reason the reason the connection check out failed
      * @since 4.10
+     * @deprecated Prefer {@link ConnectionCheckOutFailedEvent#ConnectionCheckOutFailedEvent(ServerId, long, Reason, long)}.
+     * If this constructor is used, then {@link #getElapsedTime(TimeUnit)} is 0.
      */
+    @Deprecated
     public ConnectionCheckOutFailedEvent(final ServerId serverId, final long operationId, final Reason reason) {
-        this.serverId = notNull("serverId", serverId);
-        this.operationId = operationId;
-        this.reason = notNull("reason", reason);
+        this(serverId, operationId, reason, 0);
     }
 
     /**
@@ -77,6 +99,7 @@ public ConnectionCheckOutFailedEvent(final ServerId serverId, final long operati
      * @param serverId the server id
      * @param reason the reason the connection check out failed
      * @deprecated Prefer {@link #ConnectionCheckOutFailedEvent(ServerId, long, Reason)}
+     * If this constructor is used, then {@link #getOperationId()} is -1.
      */
     @Deprecated
     public ConnectionCheckOutFailedEvent(final ServerId serverId, final Reason reason) {
@@ -112,13 +135,35 @@ public Reason getReason() {
         return reason;
     }
 
+    /**
+     * The time it took to check out the connection.
+     * More specifically, the time elapsed between the {@link ConnectionCheckOutStartedEvent} emitted by the same checking out and this event.
+     * <p>
+     * Naturally, if a new connection was not {@linkplain ConnectionCreatedEvent created}
+     * and {@linkplain ConnectionReadyEvent established} as part of checking out,
+``     * this duration is usually not greater than {@link ConnectionPoolSettings#getMaxWaitTime(TimeUnit)},
+     * but may occasionally be greater than that, because the driver does not provide hard real-time guarantees.</p>
+     * <p>
+     * This duration does not include the time to deliver the {@link ConnectionCheckOutStartedEvent}.
+     * Be warned that this may change.</p>
+     *
+     * @param timeUnit The time unit of the result.
+     * {@link TimeUnit#convert(long, TimeUnit)} specifies how the conversion from nanoseconds to {@code timeUnit} is done.
+     * @return The time it took to establish the connection.
+     * @since VAKOTODO
+     */
+    public long getElapsedTime(final TimeUnit timeUnit) {
+        return timeUnit.convert(elapsedTimeNanos, TimeUnit.NANOSECONDS);
+    }
+
     @Override
     public String toString() {
         return "ConnectionCheckOutFailedEvent{"
                 + "server=" + serverId.getAddress()
                 + ", clusterId=" + serverId.getClusterId()
                 + ", operationId=" + operationId
                 + ", reason=" + reason
+                + ", elapsedTimeNanos=" + elapsedTimeNanos
                 + '}';
     }
 }

driver-core/src/main/com/mongodb/event/ConnectionCheckedOutEvent.java

@@ -17,7 +17,11 @@
 package com.mongodb.event;
 
 import com.mongodb.connection.ConnectionId;
+import com.mongodb.connection.ConnectionPoolSettings;
 
+import java.util.concurrent.TimeUnit;
+
+import static com.mongodb.assertions.Assertions.isTrueArgument;
 import static com.mongodb.assertions.Assertions.notNull;
 
 /**
@@ -28,24 +32,43 @@
 public final class ConnectionCheckedOutEvent {
     private final ConnectionId connectionId;
     private final long operationId;
+    private final long elapsedTimeNanos;
+
+    /**
+     * Constructs an instance.
+     *
+     * @param connectionId The connection ID. See {@link #getConnectionId()}.
+     * @param operationId The operation ID. See {@link #getOperationId()}.
+     * @param elapsedTimeNanos The time it took to check out the connection. See {@link #getElapsedTime(TimeUnit)}.
+     * @since VAKOTODO
+     */
+    public ConnectionCheckedOutEvent(final ConnectionId connectionId, final long operationId, final long elapsedTimeNanos) {
+        this.connectionId = notNull("connectionId", connectionId);
+        this.operationId = operationId;
+        isTrueArgument("waited time is not negative", elapsedTimeNanos >= 0);
+        this.elapsedTimeNanos = elapsedTimeNanos;
+    }
 
     /**
      * Construct an instance
      *
      * @param connectionId the connectionId
      * @param operationId the operation id
      * @since 4.10
+     * @deprecated Prefer {@link ConnectionCheckedOutEvent#ConnectionCheckedOutEvent(ConnectionId, long, long)}.
+     * If this constructor is used, then {@link #getElapsedTime(TimeUnit)} is 0.
      */
+    @Deprecated
     public ConnectionCheckedOutEvent(final ConnectionId connectionId, final long operationId) {
-        this.connectionId = notNull("connectionId", connectionId);
-        this.operationId = operationId;
+        this(connectionId, operationId, 0);
     }
 
     /**
      * Construct an instance
      *
      * @param connectionId the connectionId
-     * @deprecated Prefer {@link #ConnectionCheckedOutEvent(ConnectionId, long)}
+     * @deprecated Prefer {@link #ConnectionCheckedOutEvent(ConnectionId, long)}.
+     * If this constructor is used, then {@link #getOperationId()} is -1.
      */
     @Deprecated
     public ConnectionCheckedOutEvent(final ConnectionId connectionId) {
@@ -71,13 +94,35 @@ public long getOperationId() {
         return operationId;
     }
 
+    /**
+     * The time it took to check out the connection.
+     * More specifically, the time elapsed between the {@link ConnectionCheckOutStartedEvent} emitted by the same checking out and this event.
+     * <p>
+     * Naturally, if a new connection was not {@linkplain ConnectionCreatedEvent created}
+     * and {@linkplain ConnectionReadyEvent established} as part of checking out,
+     * this duration is usually not greater than {@link ConnectionPoolSettings#getMaxWaitTime(TimeUnit)},
+     * but may occasionally be greater than that, because the driver does not provide hard real-time guarantees.</p>
+     * <p>
+     * This duration does not include the time to deliver the {@link ConnectionCheckOutStartedEvent}.
+     * Be warned that this may change.</p>
+     *
+     * @param timeUnit The time unit of the result.
+     * {@link TimeUnit#convert(long, TimeUnit)} specifies how the conversion from nanoseconds to {@code timeUnit} is done.
+     * @return The time it took to establish the connection.
+     * @since VAKOTODO
+     */
+    public long getElapsedTime(final TimeUnit timeUnit) {
+        return timeUnit.convert(elapsedTimeNanos, TimeUnit.NANOSECONDS);
+    }
+
     @Override
     public String toString() {
         return "ConnectionCheckedOutEvent{"
                 + "connectionId=" + connectionId
                 + ", server=" + connectionId.getServerId().getAddress()
                 + ", clusterId=" + connectionId.getServerId().getClusterId()
                 + ", operationId=" + operationId
+                + ", elapsedTimeNanos=" + elapsedTimeNanos
                 + '}';
     }
 }