Quic specifies limits on the number of uni and bidi streams that an endpoint can create. This StreamCreationPermit is used to keep track of that limit and is expected to be used before attempting to open a Quic stream. Either of tryAcquire() or tryAcquire(long, TimeUnit, Executor) must be used before attempting to open a new stream. Stream must only be opened if that method returns true which implies the stream creation limit hasn't yet reached.

It is expected that for each of the stream types (remote uni, remote bidi, local uni and local bidi) a separate instance of StreamCreationPermit will be used.

An instance of StreamCreationPermit starts with an initial limit and that limit can be increased to newer higher values whenever necessary. The limit however cannot be reduced to a lower value.

None of the methods, including tryAcquire(long, TimeUnit, Executor) and tryAcquire() block the caller thread.

Nested and Inner Type Summary

Modifier and Type	Class and Description
private static class	StreamCreationPermit.InternalSemaphore A `AbstractQueuedLongSynchronizer` whose state represents the number of permits that have currently been acquired.
private class	StreamCreationPermit.TryAcquireTask A task which iterates over the waiting acquirers and attempt to acquire a permit.
private static record	StreamCreationPermit.Waiter

Field Summary

Modifier and Type	Field and Description
private final ConcurrentLinkedQueue<StreamCreationPermit.Waiter>	acquirers
private final SequentialScheduler	permitAcquisitionScheduler
private final StreamCreationPermit.InternalSemaphore	semaphore

Access	Constructor and Description
pack-priv	StreamCreationPermit(final long the initial max streams limit initialMaxStreams)

Method Summary

Modifier and Type	Method and Description
pack-priv long	Returns: the current limit for stream creation currentLimit() Returns the current limit for stream creation.
pack-priv boolean	Returns: true if the permit was acquired and a new stream is allowed to be opened. false otherwise. tryAcquire() Attempts to acquire a permit to open a new stream.
pack-priv CompletableFuture<Boolean>	Returns: a `CompletableFuture` whose result will be `true` if the permit was acquired and `false` otherwise tryAcquire(final long the maximum amount of time to attempt acquiring a permit, after which the `CompletableFuture` will complete with a result of `false` timeout, final TimeUnit the timeout unit unit, final Executor the executor that will be used to asynchronously complete the returned `CompletableFuture` if a permit is acquired after this method has returned executor) Attempts to acquire a permit to open a new stream.
pack-priv boolean	Returns: true if the limit was successfully increased to `newLimit`, false otherwise. tryIncreaseLimitTo(final long the new limit newLimit) Attempts to increase the limit to `newLimit`.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

acquirers	back to summary
private final ConcurrentLinkedQueue<StreamCreationPermit.Waiter> acquirers

permitAcquisitionScheduler	back to summary
private final SequentialScheduler permitAcquisitionScheduler

semaphore	back to summary
private final StreamCreationPermit.InternalSemaphore semaphore

StreamCreationPermit	back to summary
pack-priv StreamCreationPermit(final long initialMaxStreams) Parameters initialMaxStreams:long the initial max streams limit Exceptions IllegalArgumentException: if `initialMaxStreams` is less than 0 NullPointerException: if executor is null

Method Detail

currentLimit	back to summary
pack-priv long currentLimit() Returns the current limit for stream creation. Returns:long the current limit for stream creation

currentLimit

back to summary

pack-priv long currentLimit()

Returns the current limit for stream creation.

Returns:long: the current limit for stream creation

tryAcquire	back to summary
pack-priv boolean tryAcquire() Attempts to acquire a permit to open a new stream. This method does not block and returns immediately. A stream should only be opened if the permit was successfully acquired. Returns:boolean true if the permit was acquired and a new stream is allowed to be opened. false otherwise.

tryAcquire

back to summary

pack-priv boolean tryAcquire()

Attempts to acquire a permit to open a new stream. This method does not block and returns immediately. A stream should only be opened if the permit was successfully acquired.

Returns:boolean: true if the permit was acquired and a new stream is allowed to be opened. false otherwise.

tryAcquire back to summary

tryAcquire	back to summary
pack-priv CompletableFuture<Boolean> tryAcquire(final long timeout, final TimeUnit unit, final Executor executor) Attempts to acquire a permit to open a new stream. If the permit is available then this method returns immediately with a `CompletableFuture` whose result is `true`. If the permit isn't currently available then this method returns a `CompletableFuture` which completes with a result of `false` if no permits were available for the duration represented by the `timeout`. If during this `timeout` period, a permit is acquired, because of an increase in the stream limit, then the returned `CompletableFuture` completes with a result of `true`. Parameters timeout:long the maximum amount of time to attempt acquiring a permit, after which the `CompletableFuture` will complete with a result of `false` unit:TimeUnit the timeout unit executor:Executor the executor that will be used to asynchronously complete the returned `CompletableFuture` if a permit is acquired after this method has returned Returns:CompletableFuture<Boolean> a `CompletableFuture` whose result will be `true` if the permit was acquired and `false` otherwise Exceptions IllegalArgumentException: if `timeout` is negative NullPointerException: if the `executor` is null

pack-priv CompletableFuture<Boolean> tryAcquire(final long timeout, final TimeUnit unit, final Executor executor)

Attempts to acquire a permit to open a new stream. If the permit is available then this method returns immediately with a CompletableFuture whose result is true. If the permit isn't currently available then this method returns a CompletableFuture which completes with a result of false if no permits were available for the duration represented by the timeout. If during this timeout period, a permit is acquired, because of an increase in the stream limit, then the returned CompletableFuture completes with a result of true.

Parameters

timeout:long: the maximum amount of time to attempt acquiring a permit, after which the CompletableFuture will complete with a result of false
unit:TimeUnit: the timeout unit
executor:Executor: the executor that will be used to asynchronously complete the returned CompletableFuture if a permit is acquired after this method has returned

Returns:CompletableFuture<Boolean>

a CompletableFuture whose result will be true if the permit was acquired and false otherwise

Exceptions

IllegalArgumentException:: if timeout is negative
NullPointerException:: if the executor is null

tryIncreaseLimitTo back to summary

tryIncreaseLimitTo	back to summary
pack-priv boolean tryIncreaseLimitTo(final long newLimit) Attempts to increase the limit to `newLimit`. The limit will be atomically increased to the `newLimit`. If the current limit is higher than the `newLimit`, then the limit isn't changed and this method returns `false`. Parameters newLimit:long the new limit Returns:boolean true if the limit was successfully increased to `newLimit`, false otherwise.

pack-priv boolean tryIncreaseLimitTo(final long newLimit)

Attempts to increase the limit to newLimit. The limit will be atomically increased to the newLimit. If the current limit is higher than the newLimit, then the limit isn't changed and this method returns false.

Parameters

newLimit:long: the new limit

Returns:boolean

true if the limit was successfully increased to newLimit, false otherwise.

jdk.internal.net.http.quic.streams back to summary

private final Class StreamCreationPermit.InternalSemaphore

Class Inheritance

extends AbstractQueuedLongSynchronizer

java.lang.Object
java.util.concurrent.locks.AbstractOwnableSynchronizer
java.util.concurrent.locks.AbstractQueuedLongSynchronizer
jdk.internal.net.http.quic.streams.StreamCreationPermit.InternalSemaphore

A AbstractQueuedLongSynchronizer whose state represents the number of permits that have currently been acquired. This Semaphore only supports "shared" mode; i.e. exclusive mode isn't supported.

The Semaphore maintains a limit which represents the maximum number of permits that can be acquired through an instance of this class. The limit can be increased but cannot be reduced from the previous set limit.

Field Summary

Modifier and Type	Field and Description
private final AtomicLong	limit
private static final long	serialVersionUID Hides java.util.concurrent.locks.AbstractQueuedLongSynchronizer.serialVersionUID.

Constructor Summary

Access	Constructor and Description
private	InternalSemaphore(final long the initial limit, must be >=0 initialLimit)

Method Summary

Modifier and Type	Method and Description
private long	Returns: the current limit currentLimit() Returns the current limit.
protected long	Returns: -1 If no permits can be acquired. Value >=0, representing the permits that are still available for acquisition. tryAcquireShared(final long the additional permits that are requested additionalAcquisitions) Overrides java.util.concurrent.locks.AbstractQueuedLongSynchronizer.tryAcquireShared. Attempts to acquire additional permits.
private boolean	Returns: true if the limit was increased to `newLimit`. false otherwise tryIncreaseLimitTo(final long The new limit to set newLimit) Tries to increase the limit to the `newLimit`.
protected boolean	Returns: true if the permits were released, false otherwise tryReleaseShared(final long the number of permits to release releases) Overrides java.util.concurrent.locks.AbstractQueuedLongSynchronizer.tryReleaseShared. Attempts to release permits

Field Detail

limit	back to summary
private final AtomicLong limit

serialVersionUID	back to summary
private static final long serialVersionUID Hides java.util.concurrent.locks.AbstractQueuedLongSynchronizer.serialVersionUID.

Constructor Detail

InternalSemaphore	back to summary
private InternalSemaphore(final long initialLimit) Parameters initialLimit:long the initial limit, must be >=0

Method Detail

currentLimit	back to summary
private long currentLimit() Returns the current limit. Returns:long the current limit

currentLimit

back to summary

private long currentLimit()

Returns the current limit.

Returns:long: the current limit

tryAcquireShared back to summary

tryAcquireShared	back to summary
protected long tryAcquireShared(final long additionalAcquisitions) Overrides java.util.concurrent.locks.AbstractQueuedLongSynchronizer.tryAcquireShared. Attempts to acquire additional permits. If no permits can be acquired, then this method returns -1. Upon successfully acquiring the `additionalAcquisitions` this method returns a value `>=0` which represents the additional number of permits that are available for acquisition. Parameters additionalAcquisitions:long the additional permits that are requested Returns:long -1 If no permits can be acquired. Value >=0, representing the permits that are still available for acquisition. Annotations @Override

protected long tryAcquireShared(final long additionalAcquisitions)

Overrides java.util.concurrent.locks.AbstractQueuedLongSynchronizer.tryAcquireShared.

Attempts to acquire additional permits. If no permits can be acquired, then this method returns -1. Upon successfully acquiring the additionalAcquisitions this method returns a value >=0 which represents the additional number of permits that are available for acquisition.

Parameters

additionalAcquisitions:long: the additional permits that are requested

Returns:long

-1 If no permits can be acquired. Value >=0, representing the permits that are still available for acquisition.

Annotations

@Override

tryIncreaseLimitTo back to summary

tryIncreaseLimitTo	back to summary
private boolean tryIncreaseLimitTo(final long newLimit) Tries to increase the limit to the `newLimit`. If the `newLimit` is lesser than the current limit, then this method returns false. Otherwise, this method will attempt to atomically increase the limit to `newLimit`. Parameters newLimit:long The new limit to set Returns:boolean true if the limit was increased to `newLimit`. false otherwise

private boolean tryIncreaseLimitTo(final long newLimit)

Tries to increase the limit to the newLimit. If the newLimit is lesser than the current limit, then this method returns false. Otherwise, this method will attempt to atomically increase the limit to newLimit.

Parameters

newLimit:long: The new limit to set

Returns:boolean

true if the limit was increased to newLimit. false otherwise

tryReleaseShared back to summary

tryReleaseShared	back to summary
protected boolean tryReleaseShared(final long releases) Overrides java.util.concurrent.locks.AbstractQueuedLongSynchronizer.tryReleaseShared. Attempts to release permits Parameters releases:long the number of permits to release Returns:boolean true if the permits were released, false otherwise Annotations @Override Exceptions IllegalArgumentException: if the number of `releases` exceeds the total number of permits that have been acquired

protected boolean tryReleaseShared(final long releases)

Overrides java.util.concurrent.locks.AbstractQueuedLongSynchronizer.tryReleaseShared.

Attempts to release permits

Parameters

releases:long: the number of permits to release

Returns:boolean

true if the permits were released, false otherwise

Annotations

@Override

Exceptions

IllegalArgumentException:: if the number of releases exceeds the total number of permits that have been acquired

jdk.internal.net.http.quic.streams back to summary

private final Class StreamCreationPermit.TryAcquireTask

Class Inheritance

extends Object
implements Runnable

java.lang.Object
jdk.internal.net.http.quic.streams.StreamCreationPermit.TryAcquireTask

All Implemented Interfaces

java.lang.Runnable

A task which iterates over the waiting acquirers and attempt to acquire a permit. If successful, the waiting acquirer(s) (i.e. the CompletableFuture(s)) are completed successfully. If not, the waiting acquirers continue to stay in the wait list

Constructor Summary

Access	Constructor and Description
private	TryAcquireTask()

Method Summary

Modifier and Type	Method and Description
public void	run() Implements java.lang.Runnable.run. Runs this operation.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Constructor Detail

TryAcquireTask	back to summary
private TryAcquireTask()

Method Detail

run	back to summary
public void run() Implements java.lang.Runnable.run. Doc from java.lang.Runnable.run. Runs this operation. Annotations @Override

run

back to summary

public void run()

Implements java.lang.Runnable.run.

Doc from java.lang.Runnable.run.

Runs this operation.

Annotations

@Override

jdk.internal.net.http.quic.streams back to summary

private final Record StreamCreationPermit.Waiter

Class Inheritance

extends Record

java.lang.Object
java.lang.Record
jdk.internal.net.http.quic.streams.StreamCreationPermit.Waiter

Record Components

acquirer:CompletableFuture<Boolean>
executor:Executor

Field Summary

Modifier and Type	Field and Description
private final CompletableFuture<Boolean>	acquirer Record Component accessed by acquirer().
private final Executor	executor Record Component accessed by executor().

Constructor Summary

Access	Constructor and Description
pack-priv	Waiter(CompletableFuture<Boolean> acquirer, Executor executor)

Method Summary

Modifier and Type	Method and Description
public CompletableFuture<Boolean>	acquirer() Record Component getter of acquirer.
public final boolean	equals(Object o) Implements abstract java.lang.Record.equals. Indicates whether some other object is "equal to" this one.
public Executor	executor() Record Component getter of executor.
public final int	hashCode() Implements abstract java.lang.Record.hashCode. Returns a hash code value for the record.
public final String	toString() Implements abstract java.lang.Record.toString. Returns a string representation of the record.

Field Detail

acquirer	back to summary
private final CompletableFuture<Boolean> acquirer Record Component accessed by acquirer().

executor	back to summary
private final Executor executor Record Component accessed by executor().

Constructor Detail

Waiter	back to summary
pack-priv Waiter(CompletableFuture<Boolean> acquirer, Executor executor)

Method Detail

acquirer	back to summary
public CompletableFuture<Boolean> acquirer() Record Component getter of acquirer.

equals back to summary

equals	back to summary
public final boolean equals(Object o) Implements abstract java.lang.Record.equals. Doc from java.lang.Record.equals. Indicates whether some other object is "equal to" this one. In addition to the general contract of `Object.equals`, record classes must further obey the invariant that when a record instance is "copied" by passing the result of the record component accessor methods to the canonical constructor, as follows: R copy = new R(r.c1(), r.c2(), ..., r.cn()); then it must be the case that `r.equals(copy)`.

public final boolean equals(Object o)

Implements abstract java.lang.Record.equals.

Doc from java.lang.Record.equals.

Indicates whether some other object is "equal to" this one. In addition to the general contract of Object.equals, record classes must further obey the invariant that when a record instance is "copied" by passing the result of the record component accessor methods to the canonical constructor, as follows:

    R copy = new R(r.c1(), r.c2(), ..., r.cn());

then it must be the case that r.equals(copy).

executor	back to summary
public Executor executor() Record Component getter of executor.

hashCode back to summary

hashCode	back to summary
public final int hashCode() Implements abstract java.lang.Record.hashCode. Doc from java.lang.Record.hashCode. Returns a hash code value for the record. Obeys the general contract of `Object.hashCode`. For records, hashing behavior is constrained by the refined contract of `Record.equals`, so that any two records created from the same components must have the same hash code.

public final int hashCode()

Implements abstract java.lang.Record.hashCode.

Doc from java.lang.Record.hashCode.

Returns a hash code value for the record. Obeys the general contract of Object.hashCode. For records, hashing behavior is constrained by the refined contract of Record.equals, so that any two records created from the same components must have the same hash code.

toString back to summary

toString	back to summary
public final String toString() Implements abstract java.lang.Record.toString. Doc from java.lang.Record.toString. Returns a string representation of the record. In accordance with the general contract of `Object#toString()`, the `toString` method returns a string that "textually represents" this record. The result should be a concise but informative representation that is easy for a person to read. In addition to this general contract, record classes must further participate in the invariant that any two records which are equal must produce equal strings. This invariant is necessarily relaxed in the rare case where corresponding equal component values might fail to produce equal strings for themselves.

public final String toString()

Implements abstract java.lang.Record.toString.

Doc from java.lang.Record.toString.

Returns a string representation of the record. In accordance with the general contract of Object#toString(), the toString method returns a string that "textually represents" this record. The result should be a concise but informative representation that is easy for a person to read.

In addition to this general contract, record classes must further participate in the invariant that any two records which are equal must produce equal strings. This invariant is necessarily relaxed in the rare case where corresponding equal component values might fail to produce equal strings for themselves.

pack-priv final Class StreamCreationPermit

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

private final Class StreamCreationPermit.InternalSemaphore

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

private final Class StreamCreationPermit.TryAcquireTask

Constructor Summary

Method Summary

Constructor Detail

Method Detail

private final Record StreamCreationPermit.Waiter

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail