Merge pull request #121 from nabijaczleweli/zram-size

Replace zram-fraction and max-zram-size with expression zram-size

Cargo.toml

@@ -10,14 +10,15 @@ license = "MIT"
 description = "Systemd unit generator for zram swap devices."
 homepage = "https://github.com/systemd/zram-generator"
 edition = "2018"
-exclude = ["tests/07a-mount-point-excl"]
+exclude = ["tests/07a-mount-point-excl", "tests/10-example"]
 
 [dependencies]
 anyhow = "1.0.12"
 clap = { version = "2.33", default-features = false }
 liboverdrop = "0.0.2"
 rust-ini = ">=0.13, <0.18"
 log = { version = "0.4", features = ["std"] }
+fasteval = { version = "0.2", default-features = false }
 
 [dev-dependencies]
 tempfile = "3"

README.md

@@ -38,11 +38,11 @@ Create `/etc/systemd/zram-generator.conf`:
 ```ini
 # /etc/systemd/zram-generator.conf
 [zram0]
-zram-fraction = 0.5
+zram-size = ram / 2
 ```
 
 A zram device will be created for each section. No actual
-configuration is necessary (the default of `zram-fraction=0.5` will be
+configuration is necessary (the default of `zram-size = min(ram / 2, 4096)` will be
 used unless overriden), but the configuration file with at least one
 section must exist.
 

man/zram-generator.conf.md

@@ -54,24 +54,13 @@ Devices with the final size of *0* will be discarded.
 
   Defaults to *none*.
 
-  For compatibility with earlier versions, `memory-limit` is allowed as an alias for this option.
-  Its use is discouraged, and administrators should migrate to `host-memory-limit`.
+* `zram-size`=
 
-* `zram-fraction`=
-
-  Defines the scaling factor of the zram device's size with relation to the total usable RAM.
-
-  This takes a nonnegative floating-point number representing that factor.
+  Sets the size of the zram device as a function of *MemTotal*, available as the `ram` variable.
 
-  Defaults to *0.5*.
+  Arithmetic operators (^%/\*-+), e, π, SI suffixes, log(), int(), ceil(), floor(), round(), abs(), min(), max(), and trigonometric functions are supported.
 
-* `max-zram-size`=
-
-  Sets the limit on the zram device's size obtained by `zram-fraction`.
-
-  This takes a nonnegative number, representing that limit in megabytes, or the literal string *none*, which can be used to override a limit set earlier.
-
-  Defaults to *4096*.
+  Defaults to *min(ram / 2, 4096)*.
 
 * `compression-algorithm`=
 
@@ -118,7 +107,7 @@ and *{/usr/lib,/usr/local/lib,/etc,/run}/systemd/zram-generator.conf* to be read
 
 The default configuration will yield the following:
 
-     zram device size [MB]
+     zram device size
          ^
          │
       4G>│               ooooooooooooo
@@ -129,10 +118,58 @@ The default configuration will yield the following:
          │     o
          │   o
     512M>│ o
-         0───────────────────────> total usable RAM [MB]
+         0───────────────────────> total usable RAM
            ^     ^       ^
            1G    4G      8G
 
+A piecewise-linear size 1:1 for the first 4G, then 1:2 above, up to a max of 32G:<br />
+&nbsp;&nbsp;`zram-size = min(min(ram, 4096) + max(ram - 4096, 0) / 2, 32 * 1024)`
+
+     zram device size
+         ^
+     32G>|                                                oooooooooooooo
+         |                                            o
+     30G>|                                        o
+         |
+        /=/
+         |
+      8G>│                           o
+         │                       o
+         │                   o
+         │               o
+         │           o
+      4G>│       o
+         │     o
+         │   o
+      1G>│ o
+         0───────────────────────────────────||──────────────────────> total usable RAM
+           ^     ^       ^               ^        ^       ^       ^
+           1G    4G      8G             12G      56G     60G     64G
+
+
+
+## OBSOLETE OPTIONS
+
+* `memory-limit`=
+
+  Compatibility alias for `host-memory-limit`.
+
+* `zram-fraction`=
+
+  Defines the scaling factor of the zram device's size with relation to the total usable RAM.
+
+  This takes a nonnegative floating-point number representing that factor.
+
+  Defaulted to *0.5*. Setting this or `max-zram-size` overrides `zram-size`.
+
+* `max-zram-size`=
+
+  Sets the limit on the zram device's size obtained by `zram-fraction`.
+
+  This takes a nonnegative number, representing that limit in megabytes, or the literal string *none*, which can be used to override a limit set earlier.
+
+  Defaulted to *4096*. Setting this or `zram-fraction` overrides `zram-size`.
+
 ## REPORTING BUGS
 
 <https://github.com/systemd/zram-generator/issues>
@@ -145,3 +182,5 @@ zram-generator(8), systemd.syntax(5), proc(5)
 
 Linux documentation of zram: <https://kernel.org/doc/html/latest/admin-guide/blockdev/zram.html><br />
      and the zram sysfs ABI: <https://kernel.org/doc/Documentation/ABI/testing/sysfs-block-zram>
+
+`fasteval` documentation for the entire `zram-size` arithmetic DSL: <https://docs.rs/fasteval/0.2.4/fasteval/#the-fasteval-expression-mini-language>