Module: Familia::Connection
- Includes:
- Middleware, Operations
- Included in:
- Familia
- Defined in:
- lib/familia/connection.rb,
lib/familia/connection/scope.rb,
lib/familia/connection/behavior.rb,
lib/familia/connection/handlers.rb,
lib/familia/connection/middleware.rb,
lib/familia/connection/operations.rb,
lib/familia/connection/operation_core.rb,
lib/familia/connection/pipelined_core.rb,
lib/familia/connection/transaction_core.rb,
lib/familia/connection/individual_command_proxy.rb
Overview
The Connection module provides Database connection management for Familia. It allows easy setup and access to Database clients across different URIs with robust connection pooling for thread safety.
Defined Under Namespace
Modules: Behavior, Handler, Middleware, OperationCore, Operations, PipelineCore, TransactionCore Classes: CachedConnectionHandler, CreateConnectionHandler, FiberConnectionHandler, FiberPipelineHandler, FiberTransactionHandler, IndividualCommandProxy, ParentDelegationHandler, ProviderConnectionHandler, ResponsibilityChain, Scope, ScopedConnectionHandler, StandaloneConnectionHandler
Constant Summary collapse
- DefaultConnectionHandler =
CreateConnectionHandler
Instance Attribute Summary collapse
-
#connection_provider ⇒ Proc
The provider should accept a URI string and return a Redis connection already connected to the correct database specified in the URI.
-
#uri ⇒ URI
(also: #url)
The default URI for Database connections.
Attributes included from Middleware
#enable_database_counter, #enable_database_logging
Instance Method Summary collapse
-
#build_connection_chain ⇒ Object
Builds the connection chain with handlers in priority order.
-
#create_dbclient(uri = nil) ⇒ Redis
(also: #connect, #isolated_dbclient)
Creates a new Database connection instance.
-
#current_connection_scope ⇒ Familia::Connection::Scope?
The connection scope the current fiber has open, or nil.
-
#dbclient(uri = nil) ⇒ Redis
Retrieves a Database connection using the Chain of Responsibility pattern.
-
#normalize_uri(uri) ⇒ Object
Normalizes various URI formats to a consistent URI object Made public so handlers can use it.
-
#with_connection_scope(uri = nil) {|Redis| ... } ⇒ Object
Runs the block inside a connection scope owned by the current fiber.
Methods included from Operations
#atomic_write, #pipelined, #transaction, #with_dbclient, #with_isolated_dbclient
Methods included from Middleware
#clear_fiber_connection!, #fiber_connection=, #increment_middleware_version!, #middleware_version, #reconnect!
Instance Attribute Details
#connection_provider ⇒ Proc
The provider should accept a URI string and return a Redis connection already connected to the correct database specified in the URI.
Contract
Familia calls the provider every time it needs a client and never hands the connection back -- there is no check-in hook. The provider must therefore return a client that remains exclusively usable by the caller without a matching check-in.
pool.with { |conn| conn } does NOT satisfy that contract: with checks
the connection back in the moment its block returns, so the client handed
to Familia is simultaneously available to every other checkout. Under
concurrency two threads end up issuing commands on one connection, and
per-connection state (MULTI, WATCH, SELECT, SUBSCRIBE) crosses callers.
ConnectionPool::Wrapper (alias ConnectionPool.wrap) does satisfy it:
it proxies each command through pool.with, so a connection is checked
out for exactly the duration of that command and checked back in
afterwards. ConnectionPool's checkout is reentrant per fiber, so a
MULTI/EXEC, a pipeline, or a WATCH-guarded transaction still runs
entirely on one connection.
Build the pool once, outside the lambda. A ConnectionPool.new inside
the provider mints a fresh pool -- and eventually a fresh connection --
on every call.
89 90 91 |
# File 'lib/familia/connection.rb', line 89 def connection_provider @connection_provider end |
#uri ⇒ URI Also known as: url
Returns The default URI for Database connections.
32 33 34 |
# File 'lib/familia/connection.rb', line 32 def uri @uri end |
Instance Method Details
#build_connection_chain ⇒ Object
Builds the connection chain with handlers in priority order
271 272 273 274 275 276 277 278 279 |
# File 'lib/familia/connection.rb', line 271 def build_connection_chain ResponsibilityChain.new .add_handler(Familia::Connection::FiberPipelineHandler.instance) .add_handler(Familia::Connection::FiberTransactionHandler.instance) .add_handler(FiberConnectionHandler.new) .add_handler(ProviderConnectionHandler.new) .add_handler(ScopedConnectionHandler.new) .add_handler(CreateConnectionHandler.new) end |
#create_dbclient(uri = nil) ⇒ Redis Also known as: connect, isolated_dbclient
Creates a new Database connection instance.
This method always creates a fresh connection and does not use caching. Each call returns a new Redis client instance that you are responsible for managing and closing when done.
127 128 129 130 131 132 133 134 |
# File 'lib/familia/connection.rb', line 127 def create_dbclient(uri = nil) parsed_uri = normalize_uri(uri) # Register middleware only once, globally register_middleware_once Redis.new(parsed_uri.conf.merge(timeout: 5)) end |
#current_connection_scope ⇒ Familia::Connection::Scope?
The connection scope the current fiber has open, or nil.
266 267 268 |
# File 'lib/familia/connection.rb', line 266 def current_connection_scope Familia::Connection::Scope.current end |
#dbclient(uri = nil) ⇒ Redis
Retrieves a Database connection using the Chain of Responsibility pattern. Handles DB selection automatically based on the URI.
Resolution order: an active pipeline or transaction connection, a fiber-local connection, the #connection_provider, the client held by an open #with_connection_scope, and finally CreateConnectionHandler.
Cost of the fallback
With no provider and no open scope, every call that reaches the
fallback returns a new Redis client. The client connects lazily, on
its first command, and nothing closes it: each lookup that goes on to
issue a command costs a TCP connection that stays open until the client
is garbage collected, and the socket lingers in TIME_WAIT after that. A
loop that calls dbclient per iteration therefore creates one
connection per iteration. That default is kept on purpose, so a bare
Familia.dbclient in a console or script keeps working with no setup.
Code that issues more than a handful of commands should hold a connection instead:
- A request, job, script or test: wrap the unit of work in #with_connection_scope. Lookups inside the block share one client per URI and the clients are closed when the block exits.
- A long-running, multi-threaded process: configure a pooled #connection_provider; the scope steps aside when a provider is set.
Thread-safe: Uses double-checked locking pattern to avoid mutex overhead on the hot path. Only acquires mutex during initial lazy initialization. MRI's GIL provides implicit memory barriers making this pattern safe.
173 174 175 176 177 178 179 180 181 182 |
# File 'lib/familia/connection.rb', line 173 def dbclient(uri = nil) # Fast path - read with local variable to ensure single read chain = @connection_chain return chain.handle(uri) if chain # Slow path - initialization only @connection_chain_mutex.synchronize do @connection_chain ||= build_connection_chain end.handle(uri) end |
#normalize_uri(uri) ⇒ Object
Normalizes various URI formats to a consistent URI object Made public so handlers can use it
283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 |
# File 'lib/familia/connection.rb', line 283 def normalize_uri(uri) case uri when Integer new_uri = Familia.uri.dup new_uri.db = uri new_uri when ->(obj) { obj.is_a?(String) || obj.instance_of?(::String) } URI.parse(uri) when URI uri when nil Familia.uri else raise ArgumentError, "Invalid URI type: #{uri.class.name}" end end |
#with_connection_scope(uri = nil) {|Redis| ... } ⇒ Object
Runs the block inside a connection scope owned by the current fiber.
While the block runs, every dbclient lookup in this fiber that would
otherwise create a fresh client (no #connection_provider, no
class-level @dbclient) resolves to one client per distinct connection
configuration, held by the scope. When the block exits, by return or by
exception, the scope closes every client it created. This bounds
connection creation to one per URI per scope, however many lookups the
block performs.
The block receives the scope's client for uri (the default URI when
nil), resolved through #dbclient; inside an open transaction or
pipeline that is the transaction or pipeline connection.
Semantics
- Nesting: a scope opened inside an active scope of the same fiber joins it. Nothing is acquired or released until the outer block exits.
- Transactions and pipelines:
transaction,pipelined,atomic_writeand WATCH-guarded writes inside the block run on the scope's client for their URI, so the commands of one operation share one socket. - Ownership: the scope belongs to the fiber that opened it. Threads and fibers spawned inside the block inherit a copy of fiber storage but are not the owner, so they do not see the scope and resolve connections as if none were open. Open a scope in each thread or fiber that needs one.
- Providers and class-level clients: a fiber-local connection set
with Familia::Connection::Middleware#fiber_connection=, a configured #connection_provider and a
class
@dbclienttake precedence over the scope, which then holds nothing for those lookups. - Fork: a client created before
forkis aRedisobject whose underlyingRedisClientcloses an inherited socket and reconnects when it notices the process id changed, so a scope that spans a fork keeps working in the child on the child's own sockets. The parent's sockets are not affected. Opening the scope after the fork avoids the question. - Reset:
Familia.reconnect!and the setters that bumpmiddleware_versionmake the scope retire its clients on the next lookup: new lookups get fresh clients, and the retired ones stay open until the block exits so a handle the block holds, or a WATCH in flight on it, keeps its connection. #current_connection_scope exposes the scope for inspection and an explicit Familia::Connection::Scope#release!, which releases it for the rest of the block. After it, plain lookups resolve as if no scope were open, and a +with_connection_scope+ opened later in the block opens a new scope of its own. - Limits: a client reference kept past the block reconnects on its
next command as an unowned connection.
Enumerator#nextruns its enumerator in a fiber of its own, so lookups made there resolve as if no scope were open. Per-connection state set on a scope client (SELECT, CLIENT SETNAME, SUBSCRIBE) is visible to every later lookup for that URI in the block.
259 260 261 |
# File 'lib/familia/connection.rb', line 259 def with_connection_scope(uri = nil) Familia::Connection::Scope.open { yield dbclient(uri) } end |