March Docs

ChannelServer

ChannelServer module: runtime helpers for Phoenix-style channel processes.

This module provides the building blocks for implementing channel processes using March's actor system. The actual actor declarations must be provided by the application (actors cannot be spawned from closures in March).

A channel process is an actor that:

  1. Receives a ChannelJoin message with topic/params.
  2. Calls the handler's join/3 callback.
  3. On success, subscribes to PubSub for the topic.
  4. Loops receiving ChannelMailbox messages and dispatching to callbacks.
  5. On ChannelLeave, unsubscribes from PubSub and calls leave/3.

Example actor using these helpers:

actor MyChannelProcess do state = ChannelServer.init_state()

on ChannelIn(ref, event, payload) -> ChannelServer.handle_in_msg(state, ref, event, payload)

on ChannelBroadcast(topic, event, payload) -> ChannelServer.handle_broadcast(state, topic, event, payload)

on ChannelLeave(reason) -> ChannelServer.handle_leave(state, reason) end

PubSub shard actors are similarly declared by the framework user:

actor PubSubShard do state = PubSub.new_state()

on PubSubSubscribe(topic, pid) -> PubSub.subscribe_state(state, topic, pid)

on PubSubUnsubscribe(topic, pid) -> PubSub.unsubscribe_state(state, topic, pid)

on PubSubBroadcast(topic, excl, event, payload) -> PubSub.broadcast_to(PubSub.get_subscribers(state, topic), excl, event, payload) state end

Types

typeJoinResultJoinResult(a) = JoinOk(a) | JoinErr(String)#
typeChannelConfigChannelConfig(a, b, c, d, e) = ChannelConfig(#

Functions

fnmake_configmake_config(socket, join_fn, handle_in_fn, handle_info_fn, leave_fn, shard_pid)#

Construct a ChannelConfig.

fnconfig_socketconfig_socket(cfg)#

Extract the socket from a config.

fnconfig_shardconfig_shard(cfg)#

Extract the pubsub shard pid from a config.

fndo_joindo_join(cfg, topic, params_json)#

Perform the join handshake. Calls join_fn, subscribes to PubSub on success. Returns JoinOk(state) or JoinErr(reason). Must be called from within an actor handler (requires actor runtime).

fndo_leavedo_leave(cfg, st, reason_str)#

Perform the leave teardown. Unsubscribes from PubSub, calls leave_fn. Must be called from within an actor handler (requires actor runtime).

fnapply_resultapply_result(cfg, result, ref)#

Apply a HandleResult: if Reply, send the reply to the transport; return the new state. For Stop, call do_leave. Returns the new channel state. Must be called from within an actor handler (requires actor runtime).

fnhandle_broadcasthandle_broadcast(cfg, event, payload_json)#

Handle a ChannelBroadcast message received by a channel process. Forwards the event+payload to the transport pid. Must be called from within an actor handler (requires actor runtime).

fnhandle_broadcast_fromhandle_broadcast_from(cfg, excl_pid, event, payload_json)#

Handle a ChannelBroadcastFrom message. Forwards event+payload to the transport unless this process is excluded. Must be called from within an actor handler (requires actor runtime).

fnshard_handle_subscribeshard_handle_subscribe(ps_state, topic, pid)#

Process a PubSubSubscribe message inside a shard actor. Returns the new PubSubState.

fnshard_handle_unsubscribeshard_handle_unsubscribe(ps_state, topic, pid)#

Process a PubSubUnsubscribe message inside a shard actor. Returns the new PubSubState.

fnshard_handle_broadcastshard_handle_broadcast(ps_state, topic, excluded_opt, event, payload_json)#

Process a PubSubBroadcast message inside a shard actor. Fans out to all subscribers, optionally excluding a pid. Returns the PubSubState unchanged.

fnselect_shardselect_shard(shards, topic)#

Select the shard pid for topic from a list of shard pids. Uses PubSub.topic_shard for consistent routing.