From 0103432a9adc32ea007eadf6209c44d6653e58c2 Mon Sep 17 00:00:00 2001 From: David Heinemeier Hansson Date: Tue, 7 Jul 2015 23:13:00 +0200 Subject: Finished class documentation --- lib/action_cable/remote_connections.rb | 1 + lib/action_cable/server/base.rb | 19 +++++++++++++++---- lib/action_cable/server/broadcasting.rb | 21 +++++++++++++++++++++ lib/action_cable/server/configuration.rb | 2 ++ lib/action_cable/server/connections.rb | 3 +++ lib/action_cable/server/worker.rb | 1 + 6 files changed, 43 insertions(+), 4 deletions(-) (limited to 'lib') diff --git a/lib/action_cable/remote_connections.rb b/lib/action_cable/remote_connections.rb index df390073de..ae7145891c 100644 --- a/lib/action_cable/remote_connections.rb +++ b/lib/action_cable/remote_connections.rb @@ -42,6 +42,7 @@ module ActionCable server.broadcast internal_redis_channel, type: 'disconnect' end + # Returns all the identifiers that were applied to this connection. def identifiers server.connection_identifiers end diff --git a/lib/action_cable/server/base.rb b/lib/action_cable/server/base.rb index 3d1d9e71ff..23cd8388bd 100644 --- a/lib/action_cable/server/base.rb +++ b/lib/action_cable/server/base.rb @@ -1,5 +1,9 @@ module ActionCable module Server + # A singleton ActionCable::Server instance is available via ActionCable.server. It's used by the rack process that starts the cable server, but + # also by the user to reach the RemoteConnections instead for finding and disconnecting connections across all servers. + # + # Also, this is the server instance used for broadcasting. See Broadcasting for details. class Base include ActionCable::Server::Broadcasting include ActionCable::Server::Connections @@ -12,14 +16,22 @@ module ActionCable def initialize end + # Called by rack to setup the server. def call(env) config.connection_class.new(self, env).process end + # Gateway to RemoteConnections. See that class for details. + def remote_connections + @remote_connections ||= RemoteConnections.new(self) + end + + # The thread worker pool for handling all the connection work on this server. Default size is set by config.worker_pool_size. def worker_pool @worker_pool ||= ActionCable::Server::Worker.pool(size: config.worker_pool_size) end + # Requires and returns an array of all the channel class constants in this application. def channel_classes @channel_classes ||= begin config.channel_paths.each { |channel_path| require channel_path } @@ -27,14 +39,12 @@ module ActionCable end end - def remote_connections - @remote_connections ||= RemoteConnections.new(self) - end - + # The redis pubsub adapter used for all streams/broadcasting. def pubsub @pubsub ||= redis.pubsub end + # The EventMachine Redis instance used by the pubsub adapter. def redis @redis ||= EM::Hiredis.connect(config.redis[:url]).tap do |redis| redis.on(:reconnect_failed) do @@ -45,6 +55,7 @@ module ActionCable end end + # All the identifiers applied to the connection class associated with this server. def connection_identifiers config.connection_class.identifiers end diff --git a/lib/action_cable/server/broadcasting.rb b/lib/action_cable/server/broadcasting.rb index 105ccb2b5c..c082e87e56 100644 --- a/lib/action_cable/server/broadcasting.rb +++ b/lib/action_cable/server/broadcasting.rb @@ -1,14 +1,35 @@ module ActionCable module Server + # Broadcasting is how other parts of your application can send messages to the channel subscribers. As explained in Channel, most of the time, these + # broadcastings are streamed directly to the clients subscribed to the named broadcasting. Let's explain with a full-stack example: + # + # class WebNotificationsChannel < ApplicationCable::Channel + # def subscribed + # stream_from "web_notifications_#{current_user.id}" + # end + # end + # + # # Somewhere in your app this is called, perhaps from a NewCommentJob + # ActionCable.server.broadcast \ + # "web_notifications_1", { title: 'New things!', body: 'All shit fit for print' } + # + # # Client-side coffescript which assumes you've already requested the right to send web notifications + # BC.cable.createSubscription "WebNotificationsChannel", + # received: (data) -> + # web_notification = new Notification data['title'], body: data['body'] module Broadcasting + # Broadcast a hash directly to a named broadcasting. It'll automatically be JSON encoded. def broadcast(broadcasting, message) broadcaster_for(broadcasting).broadcast(message) end + # Returns a broadcaster for a named broadcasting that can be reused. Useful when you have a object that + # may need multiple spots to transmit to a specific broadcasting over and over. def broadcaster_for(broadcasting) Broadcaster.new(self, broadcasting) end + # The redis instance used for broadcasting. Not intended for direct user use. def broadcasting_redis @broadcasting_redis ||= Redis.new(config.redis) end diff --git a/lib/action_cable/server/configuration.rb b/lib/action_cable/server/configuration.rb index c5783f30e0..ac9fa7b085 100644 --- a/lib/action_cable/server/configuration.rb +++ b/lib/action_cable/server/configuration.rb @@ -1,5 +1,7 @@ module ActionCable module Server + # An instance of this configuration object is available via ActionCable.server.config, which allows you to tweak the configuration points + # in a Rails config initializer. class Configuration attr_accessor :logger, :log_tags attr_accessor :connection_class, :worker_pool_size diff --git a/lib/action_cable/server/connections.rb b/lib/action_cable/server/connections.rb index 4a3fa3c621..15d7c3c8c7 100644 --- a/lib/action_cable/server/connections.rb +++ b/lib/action_cable/server/connections.rb @@ -1,5 +1,8 @@ module ActionCable module Server + # Collection class for all the connections that's been established on this specific server. Remember, usually you'll run many cable servers, so + # you can't use this collection as an full list of all the connections established against your application. Use RemoteConnections for that. + # As such, this is primarily for internal use. module Connections def connections @connections ||= [] diff --git a/lib/action_cable/server/worker.rb b/lib/action_cable/server/worker.rb index aa807bdf59..01d2c25c8a 100644 --- a/lib/action_cable/server/worker.rb +++ b/lib/action_cable/server/worker.rb @@ -1,5 +1,6 @@ module ActionCable module Server + # Worker used by Server.send_async to do connection work in threads. Only for internal use. class Worker include ActiveSupport::Callbacks include Celluloid -- cgit v1.2.3