Priority API¶
Priority Tree¶
-
class
priority.
PriorityTree
(maximum_streams: int = 1000)[source]¶ A HTTP/2 Priority Tree.
This tree stores HTTP/2 streams according to their HTTP/2 priorities.
Changed in version 1.2.0: Added
maximum_streams
keyword argument.Parameters: maximum_streams ( int
) –The maximum number of streams that may be active in the priority tree at any one time. If this number is exceeded, the priority tree will raise a
TooManyStreamsError
and will refuse to insert the stream.This parameter exists to defend against the possibility of DoS attack by attempting to overfill the priority tree. If any endpoint is attempting to manage the priority of this many streams at once it is probably trying to screw with you, so it is sensible to simply refuse to play ball at that point.
While we allow the user to configure this, we don’t really expect them too, unless they want to be even more conservative than we are by default.
-
block
(stream_id: int) → None[source]¶ Marks a given stream as blocked, with no data to send.
Parameters: stream_id – The ID of the stream to block.
-
insert_stream
(stream_id: int, depends_on: Optional[int] = None, weight: int = 16, exclusive: bool = False) → None[source]¶ Insert a stream into the tree.
Parameters: - stream_id – The stream ID of the stream being inserted.
- depends_on – (optional) The ID of the stream that the new stream depends on, if any.
- weight – (optional) The weight to give the new stream. Defaults to 16.
- exclusive – (optional) Whether this new stream should be an exclusive dependency of the parent.
-
remove_stream
(stream_id: int) → None[source]¶ Removes a stream from the priority tree.
Parameters: stream_id – The ID of the stream to remove.
-
reprioritize
(stream_id: int, depends_on: Optional[int] = None, weight: int = 16, exclusive: bool = False) → None[source]¶ Update the priority status of a stream already in the tree.
Parameters: - stream_id – The stream ID of the stream being updated.
- depends_on – (optional) The ID of the stream that the stream now
depends on. If
None
, will be moved to depend on stream 0. - weight – (optional) The new weight to give the stream. Defaults to 16.
- exclusive – (optional) Whether this stream should now be an exclusive dependency of the new parent.
-
Exceptions¶
-
class
priority.
DeadlockError
[source]¶ Raised when there are no streams that can make progress: all streams are blocked.
-
class
priority.
PriorityLoop
[source]¶ An unexpected priority loop has been detected. The tree is invalid.
-
class
priority.
DuplicateStreamError
[source]¶ An attempt was made to insert a stream that already exists.
-
class
priority.
MissingStreamError
[source]¶ An operation was attempted on a stream that is not present in the tree.
-
class
priority.
TooManyStreamsError
[source]¶ An attempt was made to insert a dangerous number of streams into the priority tree at the same time.
New in version 1.2.0.