sourced-component 0.1.0 → 0.1.2
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 +4 -4
- data/CHANGELOG.md +14 -0
- data/README.md +245 -6
- data/examples/from_dir/app.rb +86 -0
- data/examples/from_dir/lib/integrations/mailer.rb +16 -0
- data/examples/from_dir/lib/queries/users/find.rb +9 -0
- data/examples/from_dir/lib/queries/users/search.rb +13 -0
- data/examples/from_dir/lib/support/formatter.rb +6 -0
- data/lib/sourced/component/dir_source.rb +187 -0
- data/lib/sourced/component/errors.rb +2 -0
- data/lib/sourced/component/events.rb +10 -1
- data/lib/sourced/component/injector.rb +46 -3
- data/lib/sourced/component/installable.rb +32 -0
- data/lib/sourced/component/reconfiguration.rb +135 -0
- data/lib/sourced/component/version.rb +1 -1
- data/lib/sourced/component.rb +503 -25
- metadata +10 -2
data/lib/sourced/component.rb
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
# frozen_string_literal: true
|
|
2
2
|
|
|
3
3
|
require 'monitor'
|
|
4
|
+
require 'set'
|
|
4
5
|
require 'tsort'
|
|
5
6
|
require 'plumb'
|
|
6
7
|
require_relative 'component/version'
|
|
@@ -14,6 +15,9 @@ require_relative 'component/graph'
|
|
|
14
15
|
require_relative 'component/events'
|
|
15
16
|
require_relative 'component/notifier'
|
|
16
17
|
require_relative 'component/tree'
|
|
18
|
+
require_relative 'component/reconfiguration'
|
|
19
|
+
require_relative 'component/dir_source'
|
|
20
|
+
require_relative 'component/installable'
|
|
17
21
|
|
|
18
22
|
module Sourced
|
|
19
23
|
# A tree of components. Every node is a Component: it can declare a type, be implemented with
|
|
@@ -31,12 +35,16 @@ module Sourced
|
|
|
31
35
|
|
|
32
36
|
# Lifecycle statuses, in order. Shared by the root (boot status) and every node.
|
|
33
37
|
# Only nodes are ever :stopped: a started node stopped by key (see #stop_component!),
|
|
34
|
-
# which can be started again.
|
|
35
|
-
|
|
38
|
+
# which can be started again. Only nodes are ever :removed either: a component a
|
|
39
|
+
# reconfiguration dropped from the tree (see #reconfigure), which is terminal.
|
|
40
|
+
STATUSES = %i[open prepared built started stopped torn_down removed].freeze
|
|
36
41
|
|
|
37
42
|
# What #mount takes: anything that returns a Component from #to_component
|
|
38
43
|
MountableInterface = Plumb::Types::Interface[:to_component]
|
|
39
44
|
|
|
45
|
+
# What #from_dir needs from a code loader, ex. a Zeitwerk::Loader (2.6.13+)
|
|
46
|
+
LoaderInterface = Plumb::Types::Interface[:cpath_expected_at, :on_setup]
|
|
47
|
+
|
|
40
48
|
# key: local segment, ex. 'db'. nil for a root that isn't mounted anywhere
|
|
41
49
|
# owner: the component that declared this node. Standalone components own themselves
|
|
42
50
|
# type: the declared type. Any for implicit nodes created as intermediate segments (namespaces)
|
|
@@ -45,8 +53,9 @@ module Sourced
|
|
|
45
53
|
|
|
46
54
|
# notifier: receives lifecycle events. See Component::Notifier and Component::Events.
|
|
47
55
|
# The root's notifier receives the events of the whole tree, so a mounted component uses its root's.
|
|
48
|
-
def initialize(owner: nil, type: Plumb::Undefined, notifier: Notifier.new)
|
|
56
|
+
def initialize(owner: nil, type: Plumb::Undefined, notifier: Notifier.new, loader: nil)
|
|
49
57
|
@notifier = NotifierInterface.parse(notifier)
|
|
58
|
+
@loader = loader && LoaderInterface.parse(loader)
|
|
50
59
|
@key = nil
|
|
51
60
|
@parent = nil
|
|
52
61
|
@owner = owner || self
|
|
@@ -57,6 +66,8 @@ module Sourced
|
|
|
57
66
|
@value = nil
|
|
58
67
|
@deferred = false # skipped by the root's #start!, see #defer
|
|
59
68
|
@held = false # not started with the tree or its dependencies: deferred, or stopped by key
|
|
69
|
+
@recycle_to = nil # the status to come back to while recycling, see #recycle_component!
|
|
70
|
+
@reconfiguration = nil # the reconfiguration in progress, on the root only. See #reconfigure
|
|
60
71
|
@deps = [].freeze # resolved deps: a node, or { segment => node } for a wildcard
|
|
61
72
|
@dep_nodes = [].freeze # every node in @deps, for sorting
|
|
62
73
|
@children = {}
|
|
@@ -67,6 +78,8 @@ module Sourced
|
|
|
67
78
|
@starting = false
|
|
68
79
|
@order = nil
|
|
69
80
|
@lock = Monitor.new
|
|
81
|
+
@dir_sources = [] # see #from_dir
|
|
82
|
+
@deferred_injections = nil # see #deferring_injections, on the root only
|
|
70
83
|
end
|
|
71
84
|
|
|
72
85
|
def root = parent ? parent.root : self
|
|
@@ -75,6 +88,21 @@ module Sourced
|
|
|
75
88
|
# The notifier lifecycle events are published to: the root's, for every component in the tree
|
|
76
89
|
def notifier = root? ? @notifier : root.notifier
|
|
77
90
|
|
|
91
|
+
# The code loader for #from_dir, ex. a Zeitwerk::Loader. Set on the root, for the whole tree
|
|
92
|
+
def loader = root? ? @loader : root.loader
|
|
93
|
+
|
|
94
|
+
def loader=(loader)
|
|
95
|
+
synchronize do
|
|
96
|
+
raise SubcomponentError, "#{path} is mounted in another component: set the loader on the root" unless root?
|
|
97
|
+
raise LockedComponentError, "can't set the loader of a locked component" if locked?
|
|
98
|
+
if all_dir_sources.any?
|
|
99
|
+
raise ArgumentError, "can't replace the loader: #from_dir already registered with #{@loader.inspect}"
|
|
100
|
+
end
|
|
101
|
+
|
|
102
|
+
@loader = LoaderInterface.parse(loader)
|
|
103
|
+
end
|
|
104
|
+
end
|
|
105
|
+
|
|
78
106
|
# Full key from the root, ex. 'sourced.db'. nil for the root
|
|
79
107
|
def path
|
|
80
108
|
return nil unless parent
|
|
@@ -87,8 +115,32 @@ module Sourced
|
|
|
87
115
|
|
|
88
116
|
# Whether the root's #start! skips it (see #defer)
|
|
89
117
|
def deferred? = @deferred
|
|
118
|
+
# Whether the tree is past :open. #mount asks this of the component being mounted
|
|
90
119
|
def locked? = root.boot_status != :open
|
|
91
120
|
|
|
121
|
+
# Whether a reconfiguration's block is running. Only ever true on the root
|
|
122
|
+
def reconfiguring? = !@reconfiguration.nil?
|
|
123
|
+
|
|
124
|
+
# Whether the tree refuses declarations: locked, unless a #reconfigure block is open
|
|
125
|
+
private def declarations_locked? = locked? && !root.reconfiguring?
|
|
126
|
+
|
|
127
|
+
# The Reconfiguration in progress, which records what its block declares
|
|
128
|
+
protected def reconfiguration = @reconfiguration
|
|
129
|
+
protected def dir_sources = @dir_sources
|
|
130
|
+
protected def deferred_injections = @deferred_injections
|
|
131
|
+
protected def all_dir_sources = [self, *index.values].flat_map { |n| n.dir_sources }
|
|
132
|
+
|
|
133
|
+
# Load the files of each #from_dir. The branch is created even if no file declares anything,
|
|
134
|
+
# and outlives its files, so a reload can always reconfigure it
|
|
135
|
+
protected def install_dir_sources!
|
|
136
|
+
@dir_sources.each do |source|
|
|
137
|
+
next if source.installed?
|
|
138
|
+
|
|
139
|
+
walk("#{source.branch}._") unless source.branch.empty? # a directory per branch otherwise, see DirSource
|
|
140
|
+
source.install!
|
|
141
|
+
end
|
|
142
|
+
end
|
|
143
|
+
|
|
92
144
|
def inspect
|
|
93
145
|
details = namespace? ? '(namespace)' : "#{type_name} (#{[implementation&.mode || 'not implemented', status, ('deferred' if deferred?)].compact.join(', ')})"
|
|
94
146
|
"#<#{self.class} #{path || '(root)'} #{details}>"
|
|
@@ -99,20 +151,28 @@ module Sourced
|
|
|
99
151
|
# comp.declare('sourced.db.logger', Logger) { Logger.new(STDOUT) }
|
|
100
152
|
def declare(ckey, type = T::Any, &default)
|
|
101
153
|
synchronize do
|
|
102
|
-
raise LockedComponentError, "can't declare #{ckey} in a locked component" if
|
|
154
|
+
raise LockedComponentError, "can't declare #{ckey} in a locked component" if declarations_locked?
|
|
103
155
|
|
|
156
|
+
reconf = root.reconfiguration
|
|
104
157
|
branch, leaf = walk(ckey)
|
|
105
158
|
node = branch.children[leaf]
|
|
106
159
|
if node.nil?
|
|
107
160
|
node = branch.attach(leaf, Component.new(owner: self, type:))
|
|
108
161
|
elsif !node.owner.equal?(self)
|
|
109
162
|
raise OwnershipError, ownership_message(node)
|
|
110
|
-
elsif !node.implicit?
|
|
163
|
+
elsif !node.implicit? && reconf.nil?
|
|
111
164
|
raise DeclarationOverrideError, "#{node.path} is already declared"
|
|
112
165
|
else
|
|
166
|
+
# Idempotent while reconfiguring: an unchanged component keeps its value and status,
|
|
167
|
+
# and a changed type marks it to be recycled
|
|
168
|
+
was = node.implicit? ? nil : node.type_name
|
|
113
169
|
node.declare_type!(type) # an implicit namespace this component created, now with a type
|
|
170
|
+
reconf&.changed!(node) if was && was != node.type_name
|
|
114
171
|
end
|
|
115
|
-
|
|
172
|
+
new_to_the_tree = reconf.nil? || reconf.new?(node)
|
|
173
|
+
reconf&.declared!(node)
|
|
174
|
+
# While reconfiguring, only new components are announced: re-declaring the rest is noise
|
|
175
|
+
emit(Events::ComponentDeclared, key: node.path, type_name: node.type_name) if new_to_the_tree
|
|
116
176
|
|
|
117
177
|
implement_node(node, Implementation.from_block([], implementer: self, mode: :singleton) { build(&default) }) if default
|
|
118
178
|
self
|
|
@@ -180,7 +240,7 @@ module Sourced
|
|
|
180
240
|
# and the alias follows it like any other dependent.
|
|
181
241
|
def alias(ckey, target)
|
|
182
242
|
synchronize do
|
|
183
|
-
raise LockedComponentError, "can't implement #{ckey} in a locked component" if
|
|
243
|
+
raise LockedComponentError, "can't implement #{ckey} in a locked component" if declarations_locked?
|
|
184
244
|
|
|
185
245
|
implement_node(node(ckey), Implementation.alias(target, implementer: self))
|
|
186
246
|
self
|
|
@@ -203,7 +263,7 @@ module Sourced
|
|
|
203
263
|
end
|
|
204
264
|
|
|
205
265
|
synchronize do
|
|
206
|
-
raise LockedComponentError, "can't implement ENV components in a locked component" if
|
|
266
|
+
raise LockedComponentError, "can't implement ENV components in a locked component" if declarations_locked?
|
|
207
267
|
|
|
208
268
|
builders = mapping.map do |source, ckey|
|
|
209
269
|
target = node(ckey)
|
|
@@ -217,6 +277,22 @@ module Sourced
|
|
|
217
277
|
end
|
|
218
278
|
end
|
|
219
279
|
|
|
280
|
+
# Implement a declared component by building +constructor+ on each read, from the components it
|
|
281
|
+
# injects: #__component_deps maps each one's key to the keyword argument it's injected as, so the
|
|
282
|
+
# component's dependencies and the constructor's arguments come from the same place.
|
|
283
|
+
# A constructor that injects nothing is built with no arguments.
|
|
284
|
+
# class Dispatcher
|
|
285
|
+
# include App.inject('logger', 'repos.users' => 'customers')
|
|
286
|
+
# end
|
|
287
|
+
# app.declare('dispatcher', Dispatcher)
|
|
288
|
+
# app.factory('dispatcher', Dispatcher) # Dispatcher.new(logger:, customers:)
|
|
289
|
+
# Keys are paths from the root of the injector's tree, so call this on that root.
|
|
290
|
+
def factory(ckey, constructor)
|
|
291
|
+
deps = constructor.respond_to?(:__component_deps) ? constructor.__component_deps : {}
|
|
292
|
+
config(ckey, deps.keys) { |*values| constructor.new(**deps.values.zip(values).to_h) }
|
|
293
|
+
self
|
|
294
|
+
end
|
|
295
|
+
|
|
220
296
|
# Defer a node under this component: the root's #start! skips it, and every component that
|
|
221
297
|
# depends on it, directly or not, since they can't start before it. Start it by key instead,
|
|
222
298
|
# ex. when its process is elected to run it (see #start_component!).
|
|
@@ -227,7 +303,7 @@ module Sourced
|
|
|
227
303
|
# implemented again. Any component can defer a node below it, like implementing one.
|
|
228
304
|
def defer(ckey)
|
|
229
305
|
synchronize do
|
|
230
|
-
raise LockedComponentError, "can't defer #{ckey} in a locked component" if
|
|
306
|
+
raise LockedComponentError, "can't defer #{ckey} in a locked component" if declarations_locked?
|
|
231
307
|
|
|
232
308
|
target = node(ckey)
|
|
233
309
|
target.defer!
|
|
@@ -254,7 +330,29 @@ module Sourced
|
|
|
254
330
|
duplicates = names.values.tally.select { |_, count| count > 1 }.keys
|
|
255
331
|
raise ArgumentError, "duplicate injected names: #{duplicates.join(', ')}" if duplicates.any?
|
|
256
332
|
|
|
257
|
-
Injector.new(names.to_h { |key, _| [key,
|
|
333
|
+
Injector.new(names.to_h { |key, _| [key, injected_node(key)] }, names)
|
|
334
|
+
end
|
|
335
|
+
|
|
336
|
+
# Run the block with injections of undeclared keys deferred, instead of raising, and return the
|
|
337
|
+
# deferred nodes, to resolve once their declarations have run. For #from_dir, whose files can
|
|
338
|
+
# inject each other's components in any order. Only on the root
|
|
339
|
+
def deferring_injections
|
|
340
|
+
synchronize do
|
|
341
|
+
raise LockedComponentError, "already deferring injections" if @deferred_injections
|
|
342
|
+
|
|
343
|
+
@deferred_injections = []
|
|
344
|
+
yield
|
|
345
|
+
@deferred_injections
|
|
346
|
+
ensure
|
|
347
|
+
@deferred_injections = nil
|
|
348
|
+
end
|
|
349
|
+
end
|
|
350
|
+
|
|
351
|
+
private def injected_node(key)
|
|
352
|
+
deferred = root.deferred_injections
|
|
353
|
+
return node(key) if deferred.nil? || declared?(key)
|
|
354
|
+
|
|
355
|
+
Injector::DeferredNode.new(self, key).tap { |n| deferred << n }
|
|
258
356
|
end
|
|
259
357
|
|
|
260
358
|
# Attach an existing standalone component as a branch. It keeps owning its declarations,
|
|
@@ -271,10 +369,13 @@ module Sourced
|
|
|
271
369
|
raise ArgumentError, "#{mountable.inspect}.to_component must return a Component, got #{sub.inspect}" unless sub.is_a?(Component)
|
|
272
370
|
|
|
273
371
|
synchronize do
|
|
274
|
-
raise LockedComponentError, "can't mount #{ckey} in a locked component" if
|
|
372
|
+
raise LockedComponentError, "can't mount #{ckey} in a locked component" if declarations_locked?
|
|
275
373
|
raise SubcomponentError, "#{sub.inspect} is already mounted in another component" unless sub.root?
|
|
276
374
|
raise SubcomponentError, "can't mount a component into its own tree" if sub.equal?(root)
|
|
277
375
|
raise LockedComponentError, "can't mount a #{sub.boot_status} component: it must be open" if sub.locked?
|
|
376
|
+
if sub.loader
|
|
377
|
+
raise SubcomponentError, "can't mount #{ckey}: it has its own loader. Set the loader on the root of the tree instead"
|
|
378
|
+
end
|
|
278
379
|
|
|
279
380
|
branch, leaf = walk(ckey)
|
|
280
381
|
if (existing = branch.children[leaf])
|
|
@@ -289,6 +390,38 @@ module Sourced
|
|
|
289
390
|
# The mountable interface (see #mount)
|
|
290
391
|
def to_component = self
|
|
291
392
|
|
|
393
|
+
# Declare components from the Ruby files matching +glob+, autoloaded by the root's #loader.
|
|
394
|
+
# Each file's key is its path relative to +root+, prefixed with +namespace+, and the constant
|
|
395
|
+
# Zeitwerk expects in it declares its components with .__install_component(declarer).
|
|
396
|
+
# See DirSource::Declarer.
|
|
397
|
+
# app.loader = loader # once, on the root: see #loader=
|
|
398
|
+
# app.from_dir('lib/**/*.rb') # lib/queries/users/search.rb => 'lib.queries.users.search'
|
|
399
|
+
# app.from_dir('app/queries/**/*.rb', root: 'app/queries', namespace: 'queries')
|
|
400
|
+
# Files are loaded on the root's #prepare!, so the components they inject are declared by then.
|
|
401
|
+
# When the loader reloads, the branch above the glob's first wildcard is reconfigured from the new
|
|
402
|
+
# constants (see #reconfigure). A failed reload leaves the tree as it was and calls +on_error+.
|
|
403
|
+
def from_dir(glob, root: Dir.pwd, namespace: nil, on_error: DirSource::DEFAULT_ON_ERROR)
|
|
404
|
+
source = synchronize do
|
|
405
|
+
# Not even while reconfiguring: sources are only installed on #prepare!
|
|
406
|
+
raise LockedComponentError, "can't add #{glob} to a locked component" if locked?
|
|
407
|
+
|
|
408
|
+
loader = self.loader
|
|
409
|
+
unless loader
|
|
410
|
+
raise MissingLoaderError,
|
|
411
|
+
"from_dir #{glob}: the tree has no code loader. Set one on the root, " \
|
|
412
|
+
"ex. Sourced::Component.new(loader: Zeitwerk::Loader.new) or root.loader = loader"
|
|
413
|
+
end
|
|
414
|
+
|
|
415
|
+
source = DirSource.new(self, glob, loader:, root:, namespace:, on_error:)
|
|
416
|
+
DirSource.check_overlaps!([*self.root.all_dir_sources, source]) # self.root: root is the keyword here
|
|
417
|
+
@dir_sources << source
|
|
418
|
+
source
|
|
419
|
+
end
|
|
420
|
+
# Outside the tree's lock: Zeitwerk calls back under its own lock, and the callback takes the tree's
|
|
421
|
+
loader.on_setup { source.reload! }
|
|
422
|
+
self
|
|
423
|
+
end
|
|
424
|
+
|
|
292
425
|
# A node under this component, by relative key
|
|
293
426
|
def node(ckey)
|
|
294
427
|
index.fetch(ckey.to_s) { raise UndeclaredComponentError, "#{ckey} is not declared in #{path || 'this component'}" }
|
|
@@ -300,6 +433,7 @@ module Sourced
|
|
|
300
433
|
def [](ckey) = node(ckey).read
|
|
301
434
|
|
|
302
435
|
def read
|
|
436
|
+
raise RemovedComponentError, "#{path} was removed from the tree" if removed?
|
|
303
437
|
raise NotBuiltError, 'component is not built yet' unless root.readable?
|
|
304
438
|
raise UndeclaredComponentError, "#{path} is a namespace, not a component" unless implementation
|
|
305
439
|
|
|
@@ -316,7 +450,11 @@ module Sourced
|
|
|
316
450
|
return self if past?(:prepared)
|
|
317
451
|
|
|
318
452
|
instrument_root(:prepare) do
|
|
453
|
+
[self, *index.values].each { |n| n.install_dir_sources! }
|
|
319
454
|
@order = resolve_order
|
|
455
|
+
# Holds start from the declarations, on a first boot only: #reresolve! must leave the ones
|
|
456
|
+
# #stop_component! set alone, or a reconfiguration would start a stopped component again
|
|
457
|
+
@order.each { |n| n.release!; n.hold! if n.deferred? }
|
|
320
458
|
@order.each { |n| instrument_component(n, :prepare) { n.prepare_node! } }
|
|
321
459
|
@boot_status = :prepared
|
|
322
460
|
end
|
|
@@ -463,6 +601,98 @@ module Sourced
|
|
|
463
601
|
end
|
|
464
602
|
end
|
|
465
603
|
|
|
604
|
+
# ---- Recycling components -------------------------------------------------------
|
|
605
|
+
|
|
606
|
+
# Run a component's whole lifecycle again, by key relative to this component: stop it if it's
|
|
607
|
+
# running, tear it down, drop its value, then prepare and build it from scratch.
|
|
608
|
+
# Every component depending on it, directly or not, is recycled too: their values were built
|
|
609
|
+
# from its old one. Its own dependencies are left alone.
|
|
610
|
+
# Each one is left in the status it had before, so a started component is started again with
|
|
611
|
+
# +context+, and one that was only built stops at built. A component that was stopped by key
|
|
612
|
+
# (or deferred) comes back built and still held: the fresh value has never run, so it waits to
|
|
613
|
+
# be started by key, as it was.
|
|
614
|
+
# If a stop or teardown hook raises, every component is still torn down and its value dropped,
|
|
615
|
+
# and the first error is re-raised before anything is prepared again. A prepare, build or start
|
|
616
|
+
# hook leaves the component where it got to. Either way, recycling again recovers: each one
|
|
617
|
+
# remembers the status to restore until a recycle completes, so a retry puts it back even when
|
|
618
|
+
# its own status no longer says it was running.
|
|
619
|
+
# The root must be built, or started, and not booting.
|
|
620
|
+
# app.recycle_component!('sourced.store')
|
|
621
|
+
def recycle_component!(ckey, context = Thread.current)
|
|
622
|
+
recycle_components!(ckey, context:)
|
|
623
|
+
end
|
|
624
|
+
|
|
625
|
+
# #recycle_component! for several keys at once: a component depending on more than one of them
|
|
626
|
+
# is recycled once, not once per key.
|
|
627
|
+
# app.recycle_components!('sourced.store', 'repos.users')
|
|
628
|
+
def recycle_components!(*ckeys, context: Thread.current)
|
|
629
|
+
synchronize do
|
|
630
|
+
nodes = ckeys.flatten.map { |ckey| recyclable_node(ckey) }
|
|
631
|
+
# Recycling nothing resolves no nodes, so it checks the tree itself, and does nothing
|
|
632
|
+
if nodes.empty?
|
|
633
|
+
check_recyclable!('components')
|
|
634
|
+
return self
|
|
635
|
+
end
|
|
636
|
+
|
|
637
|
+
recycle_nodes!(nodes, context)
|
|
638
|
+
end
|
|
639
|
+
end
|
|
640
|
+
|
|
641
|
+
# #recycle_component! for every component in the tree, in dependency order. Only the root
|
|
642
|
+
# can recycle the whole tree.
|
|
643
|
+
# app.recycle!
|
|
644
|
+
def recycle!(context = Thread.current)
|
|
645
|
+
raise_mounted!
|
|
646
|
+
synchronize do
|
|
647
|
+
check_recyclable!('the tree')
|
|
648
|
+
recycle_nodes!(order, context)
|
|
649
|
+
end
|
|
650
|
+
end
|
|
651
|
+
|
|
652
|
+
# ---- Re-configuring a booted tree ----------------------------------------------
|
|
653
|
+
|
|
654
|
+
# Re-declare one branch of a booted tree, by key relative to this component. The block declares
|
|
655
|
+
# the branch's new contents, and whatever it doesn't declare is removed.
|
|
656
|
+
# Re-declaring a key is idempotent, so a component that didn't change keeps its value and status.
|
|
657
|
+
# Re-implementing it, re-typing it, or declaring a new key recycles it (see #recycle_component!),
|
|
658
|
+
# along with its dependents and anything whose resolved deps changed, ex. a wildcard over the branch.
|
|
659
|
+
# Nothing runs any hooks until the new set is validated, so a block that raises, or a set with a
|
|
660
|
+
# missing dep or a cycle, leaves the tree as it was. Holds survive: stopped stays stopped.
|
|
661
|
+
# app.reconfigure('reactors') do |reactors|
|
|
662
|
+
# files.each { |f| reactors.declare(f.key) }
|
|
663
|
+
# changed.each { |f| reactors.component!(f.key, f.deps, &f.implementation) }
|
|
664
|
+
# end
|
|
665
|
+
# Several branches are re-declared at once, and validated together, given an Array of keys.
|
|
666
|
+
# The block gets a handle per branch:
|
|
667
|
+
# app.reconfigure(%w[users accounts]) { |users, accounts| }
|
|
668
|
+
def reconfigure(ckey, context = Thread.current, &block)
|
|
669
|
+
raise ArgumentError, "reconfigure #{ckey}: a block must declare the branch's contents" unless block
|
|
670
|
+
|
|
671
|
+
synchronize do
|
|
672
|
+
check_reconfigurable!
|
|
673
|
+
branches = Array(ckey).map { |k| reconfigurable_branch(k) }
|
|
674
|
+
reconf = Reconfiguration.new(branches, self)
|
|
675
|
+
root.reconfiguring!(reconf)
|
|
676
|
+
|
|
677
|
+
begin
|
|
678
|
+
instrument_root(:reconfigure) do
|
|
679
|
+
reconf.snapshot!
|
|
680
|
+
plan = begin
|
|
681
|
+
block.call(*reconf.branch_handles)
|
|
682
|
+
validate_reconfiguration!(reconf)
|
|
683
|
+
rescue Exception # rubocop:disable Lint/RescueException -- nothing has run yet: put the tree back, whatever it was. Always re-raised
|
|
684
|
+
reconf.rollback!
|
|
685
|
+
raise
|
|
686
|
+
end
|
|
687
|
+
commit_reconfiguration!(reconf, plan, context)
|
|
688
|
+
end
|
|
689
|
+
ensure
|
|
690
|
+
root.reconfiguring!(nil)
|
|
691
|
+
end
|
|
692
|
+
self
|
|
693
|
+
end
|
|
694
|
+
end
|
|
695
|
+
|
|
466
696
|
# A Component::Graph describing the components under this component, by full path from the root.
|
|
467
697
|
# Components are listed in dependency order once the tree is prepared, and in declaration order before that.
|
|
468
698
|
# Namespaces without an implementation are left out.
|
|
@@ -519,7 +749,7 @@ module Sourced
|
|
|
519
749
|
type:,
|
|
520
750
|
type_name:,
|
|
521
751
|
namespace: namespace?,
|
|
522
|
-
mounted:
|
|
752
|
+
mounted: mounted?,
|
|
523
753
|
implemented: !implementation.nil?,
|
|
524
754
|
mode: implementation&.mode,
|
|
525
755
|
status:,
|
|
@@ -540,11 +770,18 @@ module Sourced
|
|
|
540
770
|
|
|
541
771
|
# ---- Node internals -------------------------------------------------------------
|
|
542
772
|
|
|
773
|
+
# The nodes this one depends on, resolved on #prepare!, wildcards included. See #graph for keys
|
|
774
|
+
def dep_nodes = @dep_nodes
|
|
775
|
+
|
|
776
|
+
# Every node in dependency order, or nil before #prepare!. #ordered_nodes is the checked version
|
|
777
|
+
def order = @order
|
|
778
|
+
|
|
779
|
+
# Whether a #reconfigure dropped this node. Terminal: reading it raises RemovedComponentError
|
|
780
|
+
def removed? = status == :removed
|
|
781
|
+
|
|
543
782
|
protected def readable? = @readable
|
|
544
783
|
protected def starting? = @starting
|
|
545
784
|
protected def lock = @lock
|
|
546
|
-
protected def dep_nodes = @dep_nodes
|
|
547
|
-
protected def order = @order
|
|
548
785
|
|
|
549
786
|
private def synchronize(&) = root.lock.synchronize(&)
|
|
550
787
|
|
|
@@ -553,6 +790,29 @@ module Sourced
|
|
|
553
790
|
@type = Plumb::Composable.wrap(type)
|
|
554
791
|
end
|
|
555
792
|
|
|
793
|
+
# Back to an implicit namespace: a dropped component that still has children (see #reconfigure).
|
|
794
|
+
# Returns the implementation it had, to tear it down with, and keeps its value until then.
|
|
795
|
+
# Clearing it before the order is resolved leaves it out, and fails validation for its dependents
|
|
796
|
+
protected def undeclare_type!
|
|
797
|
+
@implicit = true
|
|
798
|
+
@type = Plumb::Types::Any
|
|
799
|
+
@deps = [].freeze
|
|
800
|
+
@dep_nodes = [].freeze
|
|
801
|
+
@implementation.tap { @implementation = nil }
|
|
802
|
+
end
|
|
803
|
+
|
|
804
|
+
# Run a reverted component's hooks with the implementation it had, then leave it a bare namespace
|
|
805
|
+
protected def teardown_reverted!(implementation)
|
|
806
|
+
return self unless pending?(:teardown)
|
|
807
|
+
|
|
808
|
+
begin
|
|
809
|
+
implementation.stop(value) if started?
|
|
810
|
+
ensure
|
|
811
|
+
implementation.teardown(value)
|
|
812
|
+
end
|
|
813
|
+
recycle_node!
|
|
814
|
+
end
|
|
815
|
+
|
|
556
816
|
protected def implement!(implementation)
|
|
557
817
|
@implementation = implementation
|
|
558
818
|
end
|
|
@@ -563,6 +823,48 @@ module Sourced
|
|
|
563
823
|
protected def release! = @held = false
|
|
564
824
|
protected def started? = status == :started
|
|
565
825
|
|
|
826
|
+
# A component mounted into another tree: it owns itself, and isn't the root of its own
|
|
827
|
+
protected def mounted? = !root? && owner.equal?(self)
|
|
828
|
+
|
|
829
|
+
# ---- Reconfiguration internals (see #reconfigure) -------------------------------
|
|
830
|
+
|
|
831
|
+
# Public because Component::Reconfiguration is a collaborator, not another Component
|
|
832
|
+
|
|
833
|
+
def reconfiguring!(reconf) = @reconfiguration = reconf
|
|
834
|
+
def restore_order!(order) = @order = order
|
|
835
|
+
|
|
836
|
+
# Re-resolve every node's deps and the order, leaving holds alone. Raises if the new set is invalid
|
|
837
|
+
def reresolve! = resolve_order
|
|
838
|
+
|
|
839
|
+
# Everything a reconfiguration can change about this node, as a frozen
|
|
840
|
+
# Reconfiguration::NodeState. #children and #index are the node's own mutable hashes, so they're
|
|
841
|
+
# copied; everything else is frozen, or a reference it has to keep as it is — its value above all
|
|
842
|
+
def capture_state
|
|
843
|
+
Reconfiguration::NodeState.new(
|
|
844
|
+
implementation:, type:, implicit: implicit?, deps:, dep_nodes:, deferred: deferred?,
|
|
845
|
+
held: held?, status:, value:, recycle_to:, children: children.dup, index: index.dup
|
|
846
|
+
)
|
|
847
|
+
end
|
|
848
|
+
|
|
849
|
+
# Every member, so a new one can't be captured and then forgotten on the way back
|
|
850
|
+
def restore_state!(state)
|
|
851
|
+
state.to_h.each { |member, value| send(:"#{member}=", value) }
|
|
852
|
+
self
|
|
853
|
+
end
|
|
854
|
+
|
|
855
|
+
# Only #capture_state and #restore_state! use these: a reconfiguration rolling back is the one
|
|
856
|
+
# thing that writes a node's state wholesale
|
|
857
|
+
private attr_reader :deps
|
|
858
|
+
private attr_writer :implementation, :type, :implicit, :deps, :dep_nodes, :deferred, :held,
|
|
859
|
+
:status, :value, :recycle_to, :children, :index
|
|
860
|
+
|
|
861
|
+
# The status a recycle is bringing this node back to, remembered before anything is torn down.
|
|
862
|
+
# A recycle that raises leaves it set, so a retry restores what the first one meant to: the
|
|
863
|
+
# node's own status is no use by then, ex. :built for one a failed start never reached
|
|
864
|
+
protected def recycle_to = @recycle_to
|
|
865
|
+
protected def recycle_to!(status) = @recycle_to = status
|
|
866
|
+
protected def recycled! = @recycle_to = nil
|
|
867
|
+
|
|
566
868
|
# Every node this one depends on, directly or not
|
|
567
869
|
protected def transitive_dependencies
|
|
568
870
|
dep_nodes.each_with_object([]) do |dep, all|
|
|
@@ -602,6 +904,22 @@ module Sourced
|
|
|
602
904
|
parent&.index!("#{key}.#{ckey}", node)
|
|
603
905
|
end
|
|
604
906
|
|
|
907
|
+
# The inverse of #index!: drop a descendant here and in every ancestor
|
|
908
|
+
protected def unindex!(ckey)
|
|
909
|
+
@index.delete(ckey)
|
|
910
|
+
parent&.unindex!("#{key}.#{ckey}")
|
|
911
|
+
end
|
|
912
|
+
|
|
913
|
+
# Drop a child and its descendants from this node's children, and from every index
|
|
914
|
+
protected def detach!(segment)
|
|
915
|
+
child = @children.delete(segment)
|
|
916
|
+
return nil unless child
|
|
917
|
+
|
|
918
|
+
child.index.each_key { |sub_key| unindex!("#{segment}.#{sub_key}") }
|
|
919
|
+
unindex!(segment)
|
|
920
|
+
child
|
|
921
|
+
end
|
|
922
|
+
|
|
605
923
|
# Resolve deps through the implementer's index. Called on #prepare!, so declaration order doesn't matter.
|
|
606
924
|
# A wildcard dep ('reactors.*') resolves to a hash of the components directly under its key, by segment,
|
|
607
925
|
# and to an empty hash if there are none.
|
|
@@ -651,6 +969,7 @@ module Sourced
|
|
|
651
969
|
|
|
652
970
|
implementation.start(value, context)
|
|
653
971
|
@status = :started
|
|
972
|
+
recycled! # whatever a recycle meant to restore, this is the node's status now
|
|
654
973
|
self
|
|
655
974
|
end
|
|
656
975
|
|
|
@@ -662,25 +981,55 @@ module Sourced
|
|
|
662
981
|
implementation.stop(value)
|
|
663
982
|
ensure
|
|
664
983
|
@status = :stopped
|
|
984
|
+
recycled! # ... and the same when a component is stopped by key
|
|
665
985
|
end
|
|
666
986
|
self
|
|
667
987
|
end
|
|
668
988
|
|
|
669
|
-
# A started node runs its stop hooks first. Teardown hooks run even if those raise
|
|
989
|
+
# A started node runs its stop hooks first. Teardown hooks run even if those raise, and the node
|
|
990
|
+
# is torn down whatever they raise (incl. Interrupt): its hooks have had their turn either way,
|
|
991
|
+
# and running them again would tear the same value down twice
|
|
670
992
|
protected def teardown_node!
|
|
671
993
|
return self unless pending?(:teardown)
|
|
672
994
|
|
|
995
|
+
was_started = started?
|
|
996
|
+
@status = :torn_down
|
|
673
997
|
begin
|
|
674
|
-
implementation.stop(value) if
|
|
998
|
+
implementation.stop(value) if was_started
|
|
675
999
|
ensure
|
|
676
1000
|
implementation.teardown(value)
|
|
677
1001
|
end
|
|
678
|
-
|
|
1002
|
+
self
|
|
1003
|
+
end
|
|
1004
|
+
|
|
1005
|
+
# Back to :open, so every hook runs again from the top (see #recycle_component!).
|
|
1006
|
+
# Keeps the node's hold, its deps and its place in the root's order: the tree is locked,
|
|
1007
|
+
# so nothing about the graph can have changed
|
|
1008
|
+
protected def recycle_node!
|
|
1009
|
+
@status = :open
|
|
1010
|
+
@value = nil
|
|
1011
|
+
self
|
|
1012
|
+
end
|
|
1013
|
+
|
|
1014
|
+
# Whether the node has been built. A torn down node keeps its value, which stays readable;
|
|
1015
|
+
# recycling drops it, back to :open, and removing it drops it for good
|
|
1016
|
+
protected def built? = !%i[open prepared removed].include?(status)
|
|
1017
|
+
|
|
1018
|
+
# Drop the value and mark the node removed, once torn down: anything still holding it (an
|
|
1019
|
+
# Injector, say) then fails loudly instead of reading a dead value. Terminal
|
|
1020
|
+
protected def remove_node!
|
|
1021
|
+
@value = nil
|
|
1022
|
+
@status = :removed
|
|
679
1023
|
self
|
|
680
1024
|
end
|
|
681
1025
|
|
|
682
1026
|
# Without the readable check: deps are read while the component is building, in dependency order
|
|
683
|
-
protected def current_value
|
|
1027
|
+
protected def current_value
|
|
1028
|
+
raise RemovedComponentError, "#{path} was removed from the tree" if removed?
|
|
1029
|
+
raise NotBuiltError, "#{path} is not built: it was torn down or recycled" if memoized? && !built?
|
|
1030
|
+
|
|
1031
|
+
memoized? ? value : build_value
|
|
1032
|
+
end
|
|
684
1033
|
|
|
685
1034
|
# Whether the value is built once, on #build!: singletons, and aliases of memoized components.
|
|
686
1035
|
# Only known once deps are resolved, on #prepare!
|
|
@@ -735,11 +1084,7 @@ module Sourced
|
|
|
735
1084
|
raise UnimplementedComponentError, "components are deferred but not implemented: #{deferred_namespaces.map(&:path).join(', ')}"
|
|
736
1085
|
end
|
|
737
1086
|
|
|
738
|
-
nodes.each
|
|
739
|
-
n.resolve_deps!
|
|
740
|
-
n.release!
|
|
741
|
-
n.hold! if n.deferred?
|
|
742
|
-
end
|
|
1087
|
+
nodes.each { |n| n.resolve_deps! }
|
|
743
1088
|
|
|
744
1089
|
each_node = ->(&b) { nodes.each(&b) }
|
|
745
1090
|
each_child = ->(n, &b) { n.dep_nodes.each(&b) }
|
|
@@ -758,7 +1103,7 @@ module Sourced
|
|
|
758
1103
|
next if !include_built && n.status == :built
|
|
759
1104
|
|
|
760
1105
|
instrument_component(n, :teardown) { n.teardown_node! }
|
|
761
|
-
rescue
|
|
1106
|
+
rescue Exception => e # rubocop:disable Lint/RescueException -- any error (incl. Interrupt) must still tear the rest down. The first is re-raised
|
|
762
1107
|
errors << e
|
|
763
1108
|
end
|
|
764
1109
|
end
|
|
@@ -784,6 +1129,138 @@ module Sourced
|
|
|
784
1129
|
target
|
|
785
1130
|
end
|
|
786
1131
|
|
|
1132
|
+
# A node to recycle by key: implemented, under a root that can be recycled
|
|
1133
|
+
private def recyclable_node(ckey)
|
|
1134
|
+
target = node(ckey)
|
|
1135
|
+
raise UndeclaredComponentError, "#{target.path} is a namespace, not a component" if target.namespace?
|
|
1136
|
+
|
|
1137
|
+
check_recyclable!(target.path)
|
|
1138
|
+
target
|
|
1139
|
+
end
|
|
1140
|
+
|
|
1141
|
+
# A branch to reconfigure: a namespace, under a tree that isn't booting or torn down
|
|
1142
|
+
private def check_reconfigurable!
|
|
1143
|
+
raise LockedComponentError, "can't reconfigure: a reconfiguration is already running" if root.reconfiguring?
|
|
1144
|
+
raise TornDownError, "can't reconfigure: the component is torn down" if root.boot_status == :torn_down
|
|
1145
|
+
raise LockedComponentError, "can't reconfigure while the root is booting" if root.starting?
|
|
1146
|
+
end
|
|
1147
|
+
|
|
1148
|
+
private def reconfigurable_branch(ckey)
|
|
1149
|
+
branch = node(ckey)
|
|
1150
|
+
unless branch.namespace?
|
|
1151
|
+
raise UndeclaredComponentError, "#{branch.path} is a component, not a namespace: reconfigure the branch above it"
|
|
1152
|
+
end
|
|
1153
|
+
|
|
1154
|
+
mounted = [branch, *branch.index.values].find { |n| n.mounted? }
|
|
1155
|
+
raise SubcomponentError, "can't reconfigure #{branch.path}: #{mounted.path} is a mounted component" if mounted
|
|
1156
|
+
|
|
1157
|
+
branch
|
|
1158
|
+
end
|
|
1159
|
+
|
|
1160
|
+
# Apply the new set structurally and re-resolve, before any hooks run: raises what a first boot
|
|
1161
|
+
# would if it's invalid, with nothing torn down yet
|
|
1162
|
+
private def validate_reconfiguration!(reconf)
|
|
1163
|
+
reverting = reconf.reverting
|
|
1164
|
+
removing = reconf.removing
|
|
1165
|
+
|
|
1166
|
+
# Each reverted component hands its implementation back, to tear down once validation passes
|
|
1167
|
+
reverted = reverting.to_h { |n| [n, n.undeclare_type!] }
|
|
1168
|
+
removing.each { |n| n.parent.detach!(n.key) }
|
|
1169
|
+
|
|
1170
|
+
# An open tree has nothing resolved or built: #prepare! validates the set when it boots
|
|
1171
|
+
{ reverted:, removing:, order: root.boot_status == :open ? nil : root.reresolve! }
|
|
1172
|
+
end
|
|
1173
|
+
|
|
1174
|
+
# Past validation, so nothing here rolls back: tear down what's going, recycle what changed
|
|
1175
|
+
private def commit_reconfiguration!(reconf, plan, context)
|
|
1176
|
+
booted = !plan[:order].nil?
|
|
1177
|
+
was = reconf.order_before.each_with_index.to_h
|
|
1178
|
+
root.restore_order!(plan[:order]) if booted
|
|
1179
|
+
|
|
1180
|
+
# Dependents first. On an open tree every hook is pending?-skipped, so this only unindexes
|
|
1181
|
+
going = plan[:removing] + plan[:reverted].keys
|
|
1182
|
+
going.sort_by { |n| -(was[n] || -1) }.each do |n|
|
|
1183
|
+
if (implementation = plan[:reverted][n])
|
|
1184
|
+
instrument_component(n, :teardown) { n.teardown_reverted!(implementation) }
|
|
1185
|
+
next
|
|
1186
|
+
end
|
|
1187
|
+
|
|
1188
|
+
instrument_component(n, :teardown) { n.teardown_node! }
|
|
1189
|
+
n.remove_node!
|
|
1190
|
+
emit(Events::ComponentRemoved, key: n.path, remover: path)
|
|
1191
|
+
end
|
|
1192
|
+
return unless booted
|
|
1193
|
+
|
|
1194
|
+
# Nothing new has a status to go back to, so it comes up to where the root is: :prepared,
|
|
1195
|
+
# :built or :started. Deferring lowers that ceiling to :built, never raises it
|
|
1196
|
+
coming_up = root.boot_status
|
|
1197
|
+
reconf.newly_components.each do |n|
|
|
1198
|
+
n.hold! if n.deferred?
|
|
1199
|
+
n.recycle_to!(n.deferred? && coming_up == :started ? :built : coming_up)
|
|
1200
|
+
end
|
|
1201
|
+
affected = reconf.affected
|
|
1202
|
+
recycle_nodes!(affected, context) if affected.any?
|
|
1203
|
+
end
|
|
1204
|
+
|
|
1205
|
+
# Whether the tree can be recycled: built or started, and not booting. +what+ names what
|
|
1206
|
+
# the caller is recycling, for the error messages
|
|
1207
|
+
private def check_recyclable!(what)
|
|
1208
|
+
raise TornDownError, "can't recycle #{what}: the component is torn down" if root.boot_status == :torn_down
|
|
1209
|
+
if root.starting?
|
|
1210
|
+
raise LockedComponentError, "can't recycle #{what} while the root is booting: it has no status to go back to"
|
|
1211
|
+
end
|
|
1212
|
+
return if %i[built started].include?(root.boot_status)
|
|
1213
|
+
|
|
1214
|
+
raise NotBuiltError, "can't recycle #{what} before the root is built: build! it first"
|
|
1215
|
+
end
|
|
1216
|
+
|
|
1217
|
+
# Tear the targets and their dependents down, drop their values, and prepare and build them
|
|
1218
|
+
# again, leaving each one in the status it had before. See #recycle_component!
|
|
1219
|
+
private def recycle_nodes!(targets, context)
|
|
1220
|
+
# Nodes come after their dependencies in the order, so one forward pass seeded with every
|
|
1221
|
+
# target reaches the same nodes as a closure per target, without the walk-per-target
|
|
1222
|
+
reached = targets.to_set
|
|
1223
|
+
root.order.each { |n| reached << n if n.dep_nodes.any? { |dep| reached.include?(dep) } }
|
|
1224
|
+
ordered = root.order.select { |n| reached.include?(n) }
|
|
1225
|
+
# What each node comes back to, remembered before anything is torn down. A node a previous
|
|
1226
|
+
# recycle left part way through keeps the status that recycle meant to restore
|
|
1227
|
+
ordered.each { |n| n.recycle_to!(n.recycle_to || n.status) }
|
|
1228
|
+
|
|
1229
|
+
instrument_root(:recycle) do
|
|
1230
|
+
# Down, dependents first. Started nodes run their stop hooks, then their teardown hooks.
|
|
1231
|
+
# Their values are dropped whatever a hook raises (incl. Interrupt): they've been torn down
|
|
1232
|
+
errors = []
|
|
1233
|
+
begin
|
|
1234
|
+
ordered.reverse.each do |n|
|
|
1235
|
+
instrument_component(n, :teardown) { n.teardown_node! }
|
|
1236
|
+
rescue Exception => e # rubocop:disable Lint/RescueException -- as #teardown_nodes: the rest are still torn down
|
|
1237
|
+
errors << e
|
|
1238
|
+
end
|
|
1239
|
+
ensure
|
|
1240
|
+
ordered.each { |n| n.recycle_node! }
|
|
1241
|
+
end
|
|
1242
|
+
raise errors.first if errors.any?
|
|
1243
|
+
|
|
1244
|
+
# And up again, in dependency order, one stage at a time, as the root boots
|
|
1245
|
+
ordered.each { |n| instrument_component(n, :prepare) { n.prepare_node! } }
|
|
1246
|
+
ordered.each do |n|
|
|
1247
|
+
# A tree that's only prepared stops there: its values are built by #build!, which is what
|
|
1248
|
+
# a process forked after #prepare! runs for itself
|
|
1249
|
+
next if n.recycle_to == :prepared
|
|
1250
|
+
|
|
1251
|
+
instrument_component(n, :build) { n.build_node! }
|
|
1252
|
+
end
|
|
1253
|
+
ordered.each do |n|
|
|
1254
|
+
next unless n.recycle_to == :started && n.dep_nodes.all? { |dep| dep.started? }
|
|
1255
|
+
|
|
1256
|
+
instrument_component(n, :start) { n.start_node!(context) }
|
|
1257
|
+
end
|
|
1258
|
+
# Only once every node is back: a recycle that raises keeps the statuses for the retry
|
|
1259
|
+
ordered.each { |n| n.recycled! }
|
|
1260
|
+
end
|
|
1261
|
+
self
|
|
1262
|
+
end
|
|
1263
|
+
|
|
787
1264
|
# ---- Telemetry ------------------------------------------------------------------
|
|
788
1265
|
|
|
789
1266
|
# Publish root.<stage>ing, run the block, and publish root.<stage>ed with its duration,
|
|
@@ -864,7 +1341,7 @@ module Sourced
|
|
|
864
1341
|
raise ArgumentError, "#{ckey}: pass either a provider or a block, not both" if provider && block
|
|
865
1342
|
|
|
866
1343
|
synchronize do
|
|
867
|
-
raise LockedComponentError, "can't implement #{ckey} in a locked component" if
|
|
1344
|
+
raise LockedComponentError, "can't implement #{ckey} in a locked component" if declarations_locked?
|
|
868
1345
|
|
|
869
1346
|
target = node(ckey)
|
|
870
1347
|
implementation = if provider
|
|
@@ -880,6 +1357,7 @@ module Sourced
|
|
|
880
1357
|
private def implement_node(target, implementation)
|
|
881
1358
|
override = !target.implementation.nil?
|
|
882
1359
|
target.implement!(implementation)
|
|
1360
|
+
root.reconfiguration&.changed!(target)
|
|
883
1361
|
emit(
|
|
884
1362
|
Events::ComponentImplemented,
|
|
885
1363
|
key: target.path,
|