duel-memcached 0.1.8 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: b719a45d1e06bbee4fea018226842ce6adf5935984eb38073265d8cf1447b273
4
- data.tar.gz: b3f15fa60a779a53fc0c41dd548b031184703c59d5ab59d3fc88049b528beccb
3
+ metadata.gz: ce5dfecc3d5c7d615414b312a878a995063d351cba8f3ce57a504fb8970dbf20
4
+ data.tar.gz: c35166c078cb15f32e855635b20f43d308949bab0d754e9188b9118f0645b92f
5
5
  SHA512:
6
- metadata.gz: e3cd126e748662aab2d79441cbd7797d41635665ce0941f20d695a22437f91d63ef2d168bcf1ce33d715b4b124de6e0de942350095306f49d3189ada454c0bfe
7
- data.tar.gz: d6203835ebf2e2914cae7c29ae60b66fc8bdb9b0a9e151b4efecf0b20f0ac97684f3b1237c918d365201b91be064b9327728cdd0631f21c82f7938590c170747
6
+ metadata.gz: c4e77fe34bdffaa2be4fb46399bd58838fdbfc9ec510a3ad84311bd0830902ceb5e72deb46689c6048d791adf6efc3f80bb4b113fc14d8363553b0a6dcfb0c55
7
+ data.tar.gz: 8821e8388af3dfc86298af454eab1a9b20fc4f3915fe30627fd60c17585bcb579ef1ef6584250fce18dacc1a53992beaa7ef35f6baa4a09e3367439af555701d
data/CHANGELOG.md CHANGED
@@ -7,6 +7,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [0.3.0] - 2026-11-20
11
+
12
+ ### Changed
13
+
14
+ - `memcached_bytes`' slack is `per_iteration:`, as Duel 0.3.0 names it,
15
+ in place of `tolerance:`: `c.measure("memcached_bytes",
16
+ per_iteration: 8)`.
17
+ - `server:` is found by `Duel.find_program`, as every Duel plugin's
18
+ is: a path (`~` expanded) as it is, or a name on the `PATH`. With
19
+ none, the error says so (`no memcached on the PATH (give
20
+ memcached's path as server:, or DUEL_MEMCACHED_SERVER)`), as
21
+ duel-mysql's and duel-postgresql's do, where it was Ruby's
22
+ `Errno::ENOENT`.
23
+ - `settings:` gives each worker's server more of its options, by their
24
+ long names, as a Hash (`settings: {"memory-limit": 256}`, passed as
25
+ `--memory-limit=256`, and a flag's value is `true`:
26
+ `"disable-cas": true`), in place of `args:`, a list of them, as
27
+ duel-postgresql's and duel-mysql's `settings:` do. They come last, so
28
+ they win over the plugin's own.
29
+ - `Duel::Memcached.flush` is `Duel::Memcached.reset`, as MySQL's and
30
+ PostgreSQL's plugins name what empties a worker's server.
31
+ - It requires Duel 0.3.0 or later (`~> 0.3.0`), the release it's
32
+ tested with, as Duel 0.3.0 changes what plugins and benchmarks call.
33
+
34
+ ## [0.2.0] - 2026-11-16
35
+
36
+ ### Added
37
+
38
+ - `tcp: true` starts each worker's server on a port of 127.0.0.1's
39
+ alone, its server `127.0.0.1:PORT`, rather than a Unix socket: the
40
+ default on Windows, whose builds of memcached have no Unix socket.
41
+
10
42
  ## [0.1.8] - 2026-11-12
11
43
 
12
44
  No changes of its own: released in step with the other Duel gems.
@@ -80,7 +112,9 @@ the MIT license. It needs Ruby 3.4 or later, Duel 0.1, and `memcached`
80
112
  `Duel::Memcached.sum` takes that reply.
81
113
 
82
114
 
83
- [Unreleased]: https://github.com/sferik/duel-ruby/compare/duel-memcached-v0.1.8...HEAD
115
+ [Unreleased]: https://github.com/sferik/duel-ruby/compare/duel-memcached-v0.3.0...HEAD
116
+ [0.3.0]: https://github.com/sferik/duel-ruby/compare/duel-memcached-v0.2.0...duel-memcached-v0.3.0
117
+ [0.2.0]: https://github.com/sferik/duel-ruby/compare/duel-memcached-v0.1.8...duel-memcached-v0.2.0
84
118
  [0.1.8]: https://github.com/sferik/duel-ruby/compare/duel-memcached-v0.1.7...duel-memcached-v0.1.8
85
119
  [0.1.7]: https://github.com/sferik/duel-ruby/compare/duel-memcached-v0.1.6...duel-memcached-v0.1.7
86
120
  [0.1.6]: https://github.com/sferik/duel-ruby/compare/duel-memcached-v0.1.5...duel-memcached-v0.1.6
data/README.md CHANGED
@@ -35,7 +35,8 @@ end
35
35
  ```
36
36
 
37
37
  > [!NOTE]
38
- > It needs `memcached` (1.6 or later) on the `PATH`.
38
+ > It needs `memcached` (1.6 or later) on the `PATH`, or its path as
39
+ > `server:`.
39
40
 
40
41
  ## Usage
41
42
 
@@ -45,17 +46,20 @@ Duel.configure { |c| c.use :memcached }
45
46
  ```
46
47
 
47
48
  Each worker's server listens only on a Unix socket in the worker's own
48
- directory, with 32 MB of memory and one thread. The socket's path is in
49
+ directory (or with `tcp: true`, on a port of 127.0.0.1's alone, as it
50
+ does by default on Windows, whose builds of memcached have no Unix
51
+ socket), with 32 MB of memory and one thread. The socket's path (or
52
+ `127.0.0.1:PORT`) is in
49
53
  `DUEL_MEMCACHED_SERVERS`, and in `MEMCACHE_SERVERS` too, so a client that
50
54
  reads that (Dalli does) finds it and nothing reaches another memcached.
51
55
  Benchmarks can call `Duel::Memcached.servers` and
52
- `Duel::Memcached.flush`:
56
+ `Duel::Memcached.reset`:
53
57
 
54
58
  ```ruby
55
59
  # duel/cache_duel.rb
56
60
  duel "cache: a hit" do
57
61
  once do
58
- Duel::Memcached.flush # empties the worker's server (over a connection of its own)
62
+ Duel::Memcached.reset # empties the worker's server (over a connection of its own)
59
63
  @cache = Dalli::Client.new(Duel::Memcached.servers) # its socket
60
64
  @cache.set("k", "v")
61
65
  end
@@ -64,25 +68,26 @@ end
64
68
  ```
65
69
 
66
70
  > [!IMPORTANT]
67
- > `Duel::Memcached.flush` is for setting up: call it in a `setup` hook,
71
+ > `Duel::Memcached.reset` is for setting up: call it in a `setup` hook,
68
72
  > or a `once` or `untimed` block. While a benchmark is measured (`Duel.measuring?`), it
69
- > raises `Duel::Error` rather than have the flush counted.
73
+ > raises `Duel::Error` rather than have its flush counted.
70
74
 
71
75
  Options:
72
76
 
73
77
  ```ruby
74
78
  c.use :memcached,
75
79
  server: "/opt/memcached/bin/memcached", # the program (default: DUEL_MEMCACHED_SERVER, or memcached)
76
- args: ["-m", "256"], # more of its options (they win)
80
+ settings: {"memory-limit": 256}, # more of its options, as --memory-limit=256 (they win: a flag's true)
77
81
  env: %w[CACHE_SERVERS], # variables given its socket besides DUEL_MEMCACHED_SERVERS (default: MEMCACHE_SERVERS)
78
- cpu: true # judge memcached_cpu too
82
+ cpu: true, # judge memcached_cpu too
83
+ tcp: true # on a port of 127.0.0.1's, its server 127.0.0.1:PORT (default: on Windows only)
79
84
  ```
80
85
 
81
86
  The metrics come from the server's `stats`, read over a connection of
82
87
  the plugin's own, opened as each worker starts (Duel's `c.in_worker`)
83
88
  and closed as it ends. `c.use :memcached` returns it, for a `.duel.rb`
84
89
  that reads the server too (`connection.value`, in a worker only).
85
- `Duel::Memcached.flush` opens a connection of its own, from the worker's
90
+ `Duel::Memcached.reset` opens a connection of its own, from the worker's
86
91
  `DUEL_MEMCACHED_SERVERS`: a flush is an operation, and its bytes count
87
92
  as any client's (so it fails while a benchmark is measured).
88
93
  `memcached_operations` counts keys, not commands: a
@@ -109,6 +114,6 @@ too fine for it).
109
114
  Duel's `c.measure` changes any of their settings, or leaves one out:
110
115
 
111
116
  ```ruby
112
- c.measure("memcached_bytes", tolerance: 8) # values whose length varies more
117
+ c.measure("memcached_bytes", per_iteration: 8) # values whose length varies more
113
118
  c.measure("memcached_misses", skip: true)
114
119
  ```
@@ -2,6 +2,6 @@
2
2
 
3
3
  module Duel
4
4
  module Memcached
5
- VERSION = "0.1.8"
5
+ VERSION = "0.3.0"
6
6
  end
7
7
  end
@@ -20,12 +20,14 @@ module Duel
20
20
  # Duel.configure { |c| c.use :memcached }
21
21
  #
22
22
  # Benchmarks can call Duel::Memcached.servers, and
23
- # Duel::Memcached.flush in setup (or untimed blocks): while a benchmark
23
+ # Duel::Memcached.reset in setup (or untimed blocks): while a benchmark
24
24
  # is measured, it fails.
25
25
  #
26
- # The server listens only on a Unix socket in the worker's directory,
27
- # with one thread (so its statistics are up to date when they're read);
28
- # the socket's path is in DUEL_MEMCACHED_SERVERS, and in
26
+ # The server listens only on a Unix socket in the worker's directory
27
+ # (or with +tcp+, on a port of 127.0.0.1's alone: by default on Windows,
28
+ # whose builds of memcached have no Unix socket), with one thread (so
29
+ # its statistics are up to date when they're read); the socket's path
30
+ # (or 127.0.0.1:PORT) is in DUEL_MEMCACHED_SERVERS, and in
29
31
  # MEMCACHE_SERVERS too (unless +env+ names others), so a client that
30
32
  # reads that (Dalli does) finds it.
31
33
  module Memcached
@@ -34,16 +36,30 @@ module Duel
34
36
  SERVERS = "DUEL_MEMCACHED_SERVERS"
35
37
 
36
38
  # Configures Duel for the plugin (c.use :memcached): the server
37
- # (+server+ is the program, +args+ more of its options) and its
39
+ # (+server+ is the program, +settings+ more of its options, by their
40
+ # long names: "memory-limit": 256, as --memory-limit=256, and a
41
+ # flag's true: "disable-cas": true, as --disable-cas) and its
38
42
  # metrics, memcached_cpu too with +cpu+. Returns the plugin's own
39
43
  # connection to it, a worker's (see Config#in_worker, and in tests,
40
44
  # Duel::Testing.in_worker).
41
- def self.configure(config, server: ENV.fetch("DUEL_MEMCACHED_SERVER", "memcached"), args: [], env: %w[MEMCACHE_SERVERS], cpu: false)
45
+ def self.configure(config, server: ENV.fetch("DUEL_MEMCACHED_SERVER", "memcached"), settings: {}, env: %w[MEMCACHE_SERVERS], cpu: false,
46
+ tcp: !Duel.unix_sockets?)
42
47
  config.prepare(:worker) do |w|
43
- socket = w.path("memcached.sock")
44
- w.spawn(*[server, "-s", socket, "-m", "32", "-t", "1"] + args)
45
- w.wait_until { Connection.ready?(socket) }
46
- ([SERVERS] + env).to_h { |name| [name, socket] }
48
+ program = Duel.find_program(server) ||
49
+ w.fail!("no #{server}#{" on the PATH" unless Duel.path?(server)} (give memcached's path as server:, or DUEL_MEMCACHED_SERVER)")
50
+ if tcp
51
+ port = w.free_port
52
+ listen = ["-l", "127.0.0.1", "-p", port.to_s]
53
+ address = "127.0.0.1:#{port}"
54
+ else
55
+ address = w.path("memcached.sock")
56
+ listen = ["-s", address]
57
+ end
58
+ # (+settings+ last: of an option given twice, the server takes the
59
+ # last.)
60
+ w.spawn(program, *listen, "-m", "32", "-t", "1", *settings.map { |name, value| (value == true) ? "--#{name}" : "--#{name}=#{value}" })
61
+ w.wait_until { Connection.ready?(address) }
62
+ ([SERVERS] + env).to_h { |name| [name, address] }
47
63
  end
48
64
  connection = config.in_worker { |w| Connection.new(servers).tap { |memcached| w.at_stop { memcached.close } } }
49
65
  config.metric(METRICS) { stats(connection.value) }.costly
@@ -59,7 +75,7 @@ module Duel
59
75
  # Values the server makes up (CAS ids, say) grow a digit now and
60
76
  # then, and so may the code's own: a byte more an iteration isn't a
61
77
  # regression.
62
- "memcached_bytes" => {kind: :counted, unit: "B", tolerance: 1, calibrate: false}
78
+ "memcached_bytes" => {kind: :counted, unit: "B", per_iteration: 1, calibrate: false}
63
79
  }
64
80
 
65
81
  # memcached_cpu's settings. Its CPU time is the whole process's (its
@@ -67,9 +83,9 @@ module Duel
67
83
  # noisy, so judged only above 300µs, against a limit of its own, not
68
84
  # across the board (where the margin is a quarter of that), and only
69
85
  # when asked for. (A metric of its own: read around every sample, as a
70
- # ratio one is, where the counted ones are read only in counting
86
+ # timed one is, where the counted ones are read only in counting
71
87
  # samples.)
72
- CPU = {kind: :ratio, unit: "µs", floor: 300, limit: 1.05, across: false}
88
+ CPU = {kind: :timed, unit: "µs", floor: 300, limit: 1.05, across: false}
73
89
 
74
90
  # The statistics each is the sum of.
75
91
  OPERATIONS = %w[cmd_get cmd_set cmd_touch cmd_flush delete_hits delete_misses incr_hits incr_misses decr_hits decr_misses].freeze
@@ -117,15 +133,16 @@ module Duel
117
133
  value
118
134
  end
119
135
 
120
- # For benchmarks: the worker's server (its socket's path).
136
+ # For benchmarks: the worker's server (its socket's path, or
137
+ # 127.0.0.1:PORT).
121
138
  def self.servers = ENV.fetch(SERVERS)
122
139
 
123
140
  # Empties it, over a connection of its own (opened and closed: a Unix
124
141
  # socket's is cheap). A flush is an operation, and its bytes count as
125
142
  # any client's: so it's for setup or untimed blocks only, and fails
126
143
  # while a benchmark is measured (Duel.measuring?).
127
- def self.flush
128
- Duel.unmeasured!("Duel::Memcached.flush")
144
+ def self.reset
145
+ Duel.unmeasured!("Duel::Memcached.reset")
129
146
 
130
147
  connection = Connection.new(servers)
131
148
  begin
@@ -147,20 +164,40 @@ module Duel
147
164
  # The most read at a time: a whole stats reply (some 2.5KB) at once.
148
165
  READ = 65_536
149
166
 
150
- def self.ready?(path)
151
- socket = UNIXSocket.new(path)
167
+ # A socket to the server at +server+: a Unix socket's path, or
168
+ # HOST:PORT, without TCP's delay before a small write (a command),
169
+ # whose reply would wait for it.
170
+ def self.socket(server)
171
+ address = address(server)
172
+ return UNIXSocket.new(server) unless address
173
+
174
+ host, port = address
175
+ # (RBS's setsockopt takes an Integer for the value, but Ruby's
176
+ # takes true too.)
177
+ TCPSocket.new(host, port).tap { |socket| socket.setsockopt(Socket::IPPROTO_TCP, Socket::TCP_NODELAY, true) } # steep:ignore ArgumentTypeMismatch
178
+ end
179
+
180
+ # The host and port of a HOST:PORT server, or nil (a Unix socket's
181
+ # path).
182
+ def self.address(server)
183
+ match = %r{\A([^:/]+):(\d+)\z}.match(server) or return
184
+ [match[1], Integer(match[2])]
185
+ end
186
+
187
+ def self.ready?(server)
188
+ connection = socket(server)
152
189
  begin
153
- socket.write("version\r\n")
154
- socket.gets.to_s.start_with?("VERSION ")
190
+ connection.write("version\r\n")
191
+ connection.gets.to_s.start_with?("VERSION ")
155
192
  ensure
156
- socket.close
193
+ connection.close
157
194
  end
158
- rescue SystemCallError, IOError # (JRuby's refusal is an IOError)
195
+ rescue SystemCallError, IOError # (JRuby's refusal on a Unix socket is an IOError)
159
196
  false
160
197
  end
161
198
 
162
- def initialize(path)
163
- @socket = UNIXSocket.new(path)
199
+ def initialize(server)
200
+ @socket = Connection.socket(server)
164
201
  @sent = @received = @own = 0
165
202
  @reply = +""
166
203
  @chunk = +""
@@ -21,11 +21,12 @@ module Duel
21
21
  NEEDLES: Hash[String, String]
22
22
 
23
23
  # Configures Duel for the plugin (c.use :memcached): the server
24
- # (+server+ is the program, +args+ more of its options, +env+ the
24
+ # (+server+ is the program, +settings+ more of its options, +env+ the
25
25
  # variables besides DUEL_MEMCACHED_SERVERS given its socket's path)
26
- # and its metrics, memcached_cpu too with +cpu+. Returns the plugin's
26
+ # and its metrics, memcached_cpu too with +cpu+, on a port of
27
+ # 127.0.0.1's with +tcp+ (by default on Windows). Returns the plugin's
27
28
  # own connection to it, a worker's.
28
- def self.configure: (Config config, ?server: String, ?args: Array[String], ?env: Array[String], ?cpu: bool) -> InWorker[Connection]
29
+ def self.configure: (Config config, ?server: String, ?settings: Hash[String | Symbol, String | Integer | true], ?env: Array[String], ?cpu: bool, ?tcp: bool) -> InWorker[Connection]
29
30
 
30
31
  # What the worker's server has done so far (but memcached_cpu), read
31
32
  # over +connection+ (the plugin's own). It allocates only its Hash.
@@ -46,11 +47,11 @@ module Duel
46
47
 
47
48
  # Empties it, over a connection of its own: in setup or untimed
48
49
  # blocks only (it fails while a benchmark is measured).
49
- def self.flush: () -> String
50
+ def self.reset: () -> String
50
51
 
51
52
  # The least a connection needs to read a server's statistics.
52
53
  class Connection
53
- @socket: UNIXSocket
54
+ @socket: UNIXSocket | TCPSocket
54
55
  @sent: Integer
55
56
  @received: Integer
56
57
  @reply: String
@@ -62,9 +63,16 @@ module Duel
62
63
  # The most read at a time.
63
64
  READ: Integer
64
65
 
65
- def self.ready?: (String path) -> bool
66
+ # A socket to the server at +server+ (a Unix socket's path, or
67
+ # HOST:PORT).
68
+ def self.socket: (String server) -> (UNIXSocket | TCPSocket)
66
69
 
67
- def initialize: (String path) -> void
70
+ # The host and port of a HOST:PORT server, or nil.
71
+ def self.address: (String server) -> [String, Integer]?
72
+
73
+ def self.ready?: (String server) -> bool
74
+
75
+ def initialize: (String server) -> void
68
76
 
69
77
  # The server's statistics, by name.
70
78
  def stats: () -> Hash[String, String]
metadata CHANGED
@@ -1,65 +1,68 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: duel-memcached
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.1.8
4
+ version: 0.3.0
5
5
  platform: ruby
6
6
  authors:
7
- - Erik Berlin
7
+ - Erik Berlin
8
8
  bindir: bin
9
9
  cert_chain: []
10
10
  date: 1980-01-02 00:00:00.000000000 Z
11
11
  dependencies:
12
- - !ruby/object:Gem::Dependency
13
- name: duel
14
- requirement: !ruby/object:Gem::Requirement
15
- requirements:
16
- - - "~>"
17
- - !ruby/object:Gem::Version
18
- version: '0.1'
19
- type: :runtime
20
- prerelease: false
21
- version_requirements: !ruby/object:Gem::Requirement
22
- requirements:
23
- - - "~>"
24
- - !ruby/object:Gem::Version
25
- version: '0.1'
26
- description: 'A Duel plugin: each worker gets a memcached server of its own, and every
27
- benchmark is judged on the memcached operations, misses and bytes it took too.'
12
+ - !ruby/object:Gem::Dependency
13
+ name: duel
14
+ requirement: !ruby/object:Gem::Requirement
15
+ requirements:
16
+ -
17
+ - ~>
18
+ - !ruby/object:Gem::Version
19
+ version: 0.3.0
20
+ type: :runtime
21
+ prerelease: false
22
+ version_requirements: !ruby/object:Gem::Requirement
23
+ requirements:
24
+ -
25
+ - ~>
26
+ - !ruby/object:Gem::Version
27
+ version: 0.3.0
28
+ description: "A Duel plugin: each worker gets a memcached server of its own, and every benchmark is judged on the memcached operations, misses and bytes it took too."
28
29
  email:
29
- - sferik@gmail.com
30
+ - sferik@gmail.com
30
31
  executables: []
31
32
  extensions: []
32
33
  extra_rdoc_files: []
33
34
  files:
34
- - CHANGELOG.md
35
- - LICENSE
36
- - README.md
37
- - lib/duel/memcached.rb
38
- - lib/duel/memcached/version.rb
39
- - sig/duel/memcached.rbs
40
- homepage: https://github.com/sferik/duel-ruby/tree/main/plugins/memcached
35
+ - CHANGELOG.md
36
+ - LICENSE
37
+ - README.md
38
+ - lib/duel/memcached.rb
39
+ - lib/duel/memcached/version.rb
40
+ - sig/duel/memcached.rbs
41
+ homepage: "https://github.com/sferik/duel-ruby/tree/main/plugins/memcached"
41
42
  licenses:
42
- - MIT
43
+ - MIT
43
44
  metadata:
44
- source_code_uri: https://github.com/sferik/duel-ruby/tree/main/plugins/memcached
45
- changelog_uri: https://github.com/sferik/duel-ruby/blob/main/plugins/memcached/CHANGELOG.md
46
- bug_tracker_uri: https://github.com/sferik/duel-ruby/issues
47
- rubygems_mfa_required: 'true'
45
+ source_code_uri: "https://github.com/sferik/duel-ruby/tree/main/plugins/memcached"
46
+ changelog_uri: "https://github.com/sferik/duel-ruby/blob/main/plugins/memcached/CHANGELOG.md"
47
+ bug_tracker_uri: "https://github.com/sferik/duel-ruby/issues"
48
+ rubygems_mfa_required: "true"
48
49
  rdoc_options: []
49
50
  require_paths:
50
- - lib
51
+ - lib
51
52
  required_ruby_version: !ruby/object:Gem::Requirement
52
53
  requirements:
53
- - - ">="
54
- - !ruby/object:Gem::Version
55
- version: '3.4'
54
+ -
55
+ - ">="
56
+ - !ruby/object:Gem::Version
57
+ version: "3.4"
56
58
  required_rubygems_version: !ruby/object:Gem::Requirement
57
59
  requirements:
58
- - - ">="
59
- - !ruby/object:Gem::Version
60
- version: '0'
60
+ -
61
+ - ">="
62
+ - !ruby/object:Gem::Version
63
+ version: "0"
61
64
  requirements: []
62
- rubygems_version: 4.0.24
65
+ rubygems_version: 4.1.0
63
66
  specification_version: 4
64
- summary: A memcached server for each Duel worker, and what it did for each benchmark
67
+ summary: "A memcached server for each Duel worker, and what it did for each benchmark"
65
68
  test_files: []