mirror of
https://github.com/libp2p/go-libp2p-core.git
synced 2025-02-10 06:40:09 +08:00
167 lines
8.7 KiB
Go
167 lines
8.7 KiB
Go
package network
|
|
|
|
import (
|
|
"github.com/libp2p/go-libp2p/core/network"
|
|
)
|
|
|
|
// ResourceManager is the interface to the network resource management subsystem.
|
|
// The ResourceManager tracks and accounts for resource usage in the stack, from the internals
|
|
// to the application, and provides a mechanism to limit resource usage according to a user
|
|
// configurable policy.
|
|
//
|
|
// Resource Management through the ResourceManager is based on the concept of Resource
|
|
// Management Scopes, whereby resource usage is constrained by a DAG of scopes,
|
|
// The following diagram illustrates the structure of the resource constraint DAG:
|
|
// System
|
|
//
|
|
// +------------> Transient.............+................+
|
|
// | . .
|
|
// +------------> Service------------- . ----------+ .
|
|
// | . | .
|
|
// +-------------> Protocol----------- . ----------+ .
|
|
// | . | .
|
|
// +--------------> Peer \ | .
|
|
// +------------> Connection | .
|
|
// | \ \
|
|
// +---------------------------> Stream
|
|
//
|
|
// The basic resources accounted by the ResourceManager include memory, streams, connections,
|
|
// and file descriptors. These account for both space and time used by
|
|
// the stack, as each resource has a direct effect on the system
|
|
// availability and performance.
|
|
//
|
|
// The modus operandi of the resource manager is to restrict resource usage at the time of
|
|
// reservation. When a component of the stack needs to use a resource, it reserves it in the
|
|
// appropriate scope. The resource manager gates the reservation against the scope applicable
|
|
// limits; if the limit is exceeded, then an error (wrapping ErrResourceLimitExceeded) and it
|
|
// is up the component to act accordingly. At the lower levels of the stack, this will normally
|
|
// signal a failure of some sorts, like failing to opening a stream or a connection, which will
|
|
// propagate to the programmer. Some components may be able to handle resource reservation failure
|
|
// more gracefully; for instance a muxer trying to grow a buffer for a window change, will simply
|
|
// retain the existing window size and continue to operate normally albeit with some degraded
|
|
// throughput.
|
|
// All resources reserved in some scope are released when the scope is closed. For low level
|
|
// scopes, mainly Connection and Stream scopes, this happens when the connection or stream is
|
|
// closed.
|
|
//
|
|
// Service programmers will typically use the resource manager to reserve memory
|
|
// for their subsystem.
|
|
// This happens with two avenues: the programmer can attach a stream to a service, whereby
|
|
// resources reserved by the stream are automatically accounted in the service budget; or the
|
|
// programmer may directly interact with the service scope, by using ViewService through the
|
|
// resource manager interface.
|
|
//
|
|
// Application programmers can also directly reserve memory in some applicable scope. In order
|
|
// to facilitate control flow delimited resource accounting, all scopes defined in the system
|
|
// allow for the user to create spans. Spans are temporary scopes rooted at some
|
|
// other scope and release their resources when the programmer is done with them. Span
|
|
// scopes can form trees, with nested spans.
|
|
//
|
|
// Typical Usage:
|
|
// - Low level components of the system (transports, muxers) all have access to the resource
|
|
// manager and create connection and stream scopes through it. These scopes are accessible
|
|
// to the user, albeit with a narrower interface, through Conn and Stream objects who have
|
|
// a Scope method.
|
|
// - Services typically center around streams, where the programmer can attach streams to a
|
|
// particular service. They can also directly reserve memory for a service by accessing the
|
|
// service scope using the ResourceManager interface.
|
|
// - Applications that want to account for their network resource usage can reserve memory,
|
|
// typically using a span, directly in the System or a Service scope; they can also
|
|
// opt to use appropriate steam scopes for streams that they create or own.
|
|
//
|
|
// User Serviceable Parts: the user has the option to specify their own implementation of the
|
|
// interface. We provide a canonical implementation in the go-libp2p-resource-manager package.
|
|
// The user of that package can specify limits for the various scopes, which can be static
|
|
// or dynamic.
|
|
//
|
|
// WARNING The ResourceManager interface is considered experimental and subject to change
|
|
//
|
|
// in subsequent releases.
|
|
//
|
|
// Deprecated: use github.com/libp2p/go-libp2p/core/network.ResourceManager instead
|
|
type ResourceManager = network.ResourceManager
|
|
|
|
// ResourceScopeViewer is a mixin interface providing view methods for accessing top level
|
|
// scopes.
|
|
// Deprecated: use github.com/libp2p/go-libp2p/core/network.ResourceScopeViewer instead
|
|
type ResourceScopeViewer = network.ResourceScopeViewer
|
|
|
|
const (
|
|
// ReservationPriorityLow is a reservation priority that indicates a reservation if the scope
|
|
// memory utilization is at 40% or less.
|
|
// Deprecated: use github.com/libp2p/go-libp2p/core/network.ReservationPriorityLow instead
|
|
ReservationPriorityLow = network.ReservationPriorityLow
|
|
// ReservationPriorityMedium is a reservation priority that indicates a reservation if the scope
|
|
// memory utilization is at 60% or less.
|
|
// Deprecated: use github.com/libp2p/go-libp2p/core/network.ReservationPriorityMedium instead
|
|
ReservationPriorityMedium uint8 = network.ReservationPriorityMedium
|
|
// ReservationPriorityHigh is a reservation prioirity that indicates a reservation if the scope
|
|
// memory utilization is at 80% or less.
|
|
// Deprecated: use github.com/libp2p/go-libp2p/core/network.ReservationPriorityHigh instead
|
|
ReservationPriorityHigh uint8 = network.ReservationPriorityHigh
|
|
// ReservationPriorityAlways is a reservation priority that indicates a reservation if there is
|
|
// enough memory, regardless of scope utilization.
|
|
// Deprecated: use github.com/libp2p/go-libp2p/core/network.ReservationPriorityAlways instead
|
|
ReservationPriorityAlways = network.ReservationPriorityAlways
|
|
)
|
|
|
|
// ResourceScope is the interface for all scopes.
|
|
// Deprecated: use github.com/libp2p/go-libp2p/core/network.ResourceScope instead
|
|
type ResourceScope = network.ResourceScope
|
|
|
|
// ResourceScopeSpan is a ResourceScope with a delimited span.
|
|
// Span scopes are control flow delimited and release all their associated resources
|
|
// when the programmer calls Done.
|
|
//
|
|
// Example:
|
|
//
|
|
// s, err := someScope.BeginSpan()
|
|
// if err != nil { ... }
|
|
// defer s.Done()
|
|
//
|
|
// if err := s.ReserveMemory(...); err != nil { ... }
|
|
// // ... use memory
|
|
//
|
|
// Deprecated: use github.com/libp2p/go-libp2p/core/network.ResourceScopeSpan instead
|
|
type ResourceScopeSpan = network.ResourceScopeSpan
|
|
|
|
// ServiceScope is the interface for service resource scopes
|
|
// Deprecated: use github.com/libp2p/go-libp2p/core/network.ServiceScope instead
|
|
type ServiceScope = network.ServiceScope
|
|
|
|
// ProtocolScope is the interface for protocol resource scopes.
|
|
// Deprecated: use github.com/libp2p/go-libp2p/core/network.ProtocolScope instead
|
|
type ProtocolScope = network.ProtocolScope
|
|
|
|
// PeerScope is the interface for peer resource scopes.
|
|
// Deprecated: use github.com/libp2p/go-libp2p/core/network.PeerScope instead
|
|
type PeerScope = network.PeerScope
|
|
|
|
// ConnManagementScope is the low level interface for connection resource scopes.
|
|
// This interface is used by the low level components of the system who create and own
|
|
// the span of a connection scope.
|
|
// Deprecated: use github.com/libp2p/go-libp2p/core/network.ConnManagementScope instead
|
|
type ConnManagementScope = network.ConnManagementScope
|
|
|
|
// ConnScope is the user view of a connection scope
|
|
// Deprecated: use github.com/libp2p/go-libp2p/core/network.ConnScope instead
|
|
type ConnScope = network.ConnScope
|
|
|
|
// StreamManagementScope is the interface for stream resource scopes.
|
|
// This interface is used by the low level components of the system who create and own
|
|
// the span of a stream scope.
|
|
// Deprecated: use github.com/libp2p/go-libp2p/core/network.StreamManagementScope instead
|
|
type StreamManagementScope = network.StreamManagementScope
|
|
|
|
// StreamScope is the user view of a StreamScope.
|
|
// Deprecated: use github.com/libp2p/go-libp2p/core/network.StreamScope instead
|
|
type StreamScope = network.StreamScope
|
|
|
|
// ScopeStat is a struct containing resource accounting information.
|
|
// Deprecated: use github.com/libp2p/go-libp2p/core/network.ScopeStat instead
|
|
type ScopeStat = network.ScopeStat
|
|
|
|
// NullResourceManager is a stub for tests and initialization of default values
|
|
// Deprecated: use github.com/libp2p/go-libp2p/core/network.NullResourceManager instead
|
|
var NullResourceManager = network.NullResourceManager
|