Update README.md

README.md

@@ -28,13 +28,13 @@ File descriptors are an important resource that uses memory (and
 computational time) at the system level. They are also a scarce
 resource, as typically (unless the user explicitly intervenes) they
 are constrained by the system. Exhaustion of file descriptors may
-render the application incapable of operating (e.g. because it is
-unable to open a file), this is important for libp2p because most
+render the application incapable of operating (e.g., because it is
+unable to open a file).  This is important for libp2p because most
 operating systems represent sockets as file descriptors.
 
 ### Connections
 
-Connections are a higher level concept endemic to libp2p; in order to
+Connections are a higher-level concept endemic to libp2p; in order to
 communicate with another peer, a connection must first be
 established. Connections are an important resource in libp2p, as they
 consume memory, goroutines, and possibly file descriptors.
@@ -198,11 +198,11 @@ uses a buffer.
 ## Limits
 
 Each resource scope has an associated limit object, which designates
-limits for all basic resources.  The limit is checked every time some
+limits for all [basic resources](#basic-resources).  The limit is checked every time some
 resource is reserved and provides the system with an opportunity to
 constrain resource usage.
 
-There are separate limits for each class of scope, allowing us for
+There are separate limits for each class of scope, allowing for
 multiresolution and aggregate resource accounting.  As such, we have
 limits for the system and transient scopes, default and specific
 limits for services, protocols, and peers, and limits for connections
@@ -223,7 +223,7 @@ used to initialize a fixed limiter as shown above) by calling the `Scale` method
 The `Scale` method takes two parameters: the amount of memory and the number of file
 descriptors that an application is willing to dedicate to libp2p.
 
-These amounts will differ between use cases: A blockchain node running on a dedicated
+These amounts will differ between use cases. A blockchain node running on a dedicated
 server might have a lot of memory, and dedicate 1/4 of that memory to libp2p. On the
 other end of the spectrum, a desktop companion application running as a background
 task on a consumer laptop will probably dedicate significantly less than 1/4 of its system
@@ -269,7 +269,7 @@ For Example, calling `Scale` with 4 GB of memory will result in a limit of 384 f
 
 The `FDFraction` defines how many of the file descriptors are allocated to this
 scope. In the example above, when called with a file descriptor value of 1000,
-this would result in a limit of 1256 file descriptors for the system scope.
+this would result in a limit of 1000 (1000 * 1) file descriptors for the system scope.
 
 Note that we only showed the configuration for the system scope here, equivalent
 configuration options apply to all other scopes as well.
@@ -278,12 +278,12 @@ configuration options apply to all other scopes as well.
 
 By default the resource manager ships with some reasonable scaling limits and
 makes a reasonable guess at how much system memory you want to dedicate to the
-go-libp2p process. For the default definitions see `DefaultLimits` and
-`ScalingLimitConfig.AutoScale()`.
+go-libp2p process. For the default definitions see [`DefaultLimits` and
+`ScalingLimitConfig.AutoScale()`](./limit_defaults.go).
 
 ### Tweaking Defaults
 
-If the defaults seem mostly okay, but you want to adjust one facet you can do
+If the defaults seem mostly okay, but you want to adjust one facet you can
 simply copy the default struct object and update the field you want to change. You can
 apply changes to a `BaseLimit`, `BaseLimitIncrease`, and `LimitConfig` with
 `.Apply`.
@@ -302,7 +302,7 @@ tweakedDefaults.ProtocolBaseLimit.Apply(BaseLimit{
 ### How to tune your limits
 
 Once you've set your limits and monitoring (see [Monitoring](#monitoring) below) you can now tune your
-limits better.  The `blocked_resources` metric will tell you what was blocked
+limits better.  ??? The `blocked_resources` metric will tell you what was blocked
 and for what scope. If you see a steady stream of these blocked requests it
 means your resource limits are too low for your usage. If you see a rare sudden
 spike, this is okay and it means the resource manager protected you from some
@@ -320,7 +320,7 @@ These errors occur whenever a limit is hit. For example you'll get this error if
 you are at your limit for the number of streams you can have, and you try to
 open one more.
 
-If you're seeing a lot of "resource limit exceeded" errors take a look at the
+??? If you're seeing a lot of "resource limit exceeded" errors take a look at the
 `blocked_resources` metric for some information on what was blocked. Also take
 a look at the resources used per stream, and per protocol (the Grafana
 Dashboard is ideal for this) and check if you're routinely hitting limits or if
@@ -335,7 +335,7 @@ routinely.
 Once you have limits set, you'll want to monitor to see if you're running into
 your limits often. This could be a sign that you need to raise your limits
 (your process is more intensive than you originally thought) or that you need
-fix something in your application (surely you don't need over 1000 streams?).
+to fix something in your application (surely you don't need over 1000 streams?).
 
 There are OpenCensus metrics that can be hooked up to the resource manager. See
 `obs/stats_test.go` for an example on how to enable this, and `DefaultViews` in
@@ -344,7 +344,7 @@ or any other OpenCensus supported platform.
 
 There is also an included Grafana dashboard to help kickstart your
 observability into the resource manager. Find more information about it at
-`./obs/grafana-dashboards/README.md`.
+[here](./obs/grafana-dashboards/README.md).
 
 ## Allowlisting multiaddrs to mitigate eclipse attacks
 
@@ -408,7 +408,7 @@ implements `net.Error` and is marked as temporary, so that the
 programmer can handle by backoff retry.
 
 ## Usage
-
+???
 This package provides a limiter implementation that applies fixed limits:
 ```go
 limiter := NewFixedLimiter(limits)

limit.go

@@ -127,6 +127,8 @@ func (l *BaseLimit) Apply(l2 BaseLimit) {
 }
 
 // BaseLimitIncrease is the increase per GB of system memory.
+// Memory is in bytes.  Values greater than 1<<30 likely don't make sense.
+// FDFraction is expected to be >= 0 and <= 1.
 type BaseLimitIncrease struct {
 	Streams         int
 	StreamsInbound  int

limit_defaults.go

@@ -254,7 +254,7 @@ func (cfg *LimitConfig) Apply(c LimitConfig) {
 }
 
 // Scale scales up a limit configuration.
-// memory is the amount of memory that the stack is allowed to consume,
+// memory is the amount of memory in bytes that the stack is allowed to consume,
 // for a full it's recommended to use 1/8 of the installed system memory.
 // If memory is smaller than 128 MB, the base configuration will be used.
 //