Skip to content

Commit

Permalink
Refactored canonical doc for realtime conn to lang specific doc
Browse files Browse the repository at this point in the history
  • Loading branch information
@sacOO7
sacOO7 committed Nov 20, 2022
1 parent 4453ea3 commit f7779b5
Show file tree
Hide file tree
Showing 2 changed files with 33 additions and 45 deletions.
3 changes: 1 addition & 2 deletions ably/realtime_client.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -41,8 +41,7 @@ func NewRealtime(options ...ClientOption) (*Realtime, error) {
}

// Connect calls Connection.Connect and causes the connection to open, entering the connecting state.
// Explicitly calling Connect() is unnecessary unless the ClientOptions.NoConnect property is enabled.
// (proxy for RTN11).
// Explicitly calling Connect() is needed if the ClientOptions.NoConnect is set true (proxy for RTN11).
func (c *Realtime) Connect() {
c.Connection.Connect()
}
Expand Down
75 changes: 32 additions & 43 deletions ably/realtime_conn.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,63 +15,55 @@ var (
errQueueing = errors.New("unable to send messages in current state with disabled queueing")
)

// connectionMode is the mode in which the connection is operating
// connectionMode is the mode in which the connection is operating.
type connectionMode uint

const (
// normalMode this is set when the Connection operating normally
// normalMode is set when the Connection operating normally.
normalMode connectionMode = iota
// resumeMode this is set when the Connection is trying to resume
// resumeMode is set when the Connection is trying to resume.
resumeMode
// recoveryMode this is set when the Connection is trying to recover
// recoveryMode is set when the Connection is trying to recover.
recoveryMode
)

// **LEGACY**
// Connection represents a single connection Realtime instantiates for
// communication with Ably servers.
// **CANONICAL**
// Enables the management of a connection to Ably.
// Connection represents a single connection Realtime instantiates for communication with Ably servers.
// It also enables the management of a connection to Ably.
type Connection struct {
mtx sync.Mutex

// on setConn we write to conn with mtx protection, however in eventLoop we
// connMtx - on setConn we write to conn with mtx protection, however in eventLoop we
// read conn unprotected, this is racy because now we establish connection in a
// separate goroutine.
//
// using mtx to protect reads in eventLoop causes a deadlock.
connMtx sync.Mutex

// **CANONICAL**
// Embeds an [EventEmitter]{@link EventEmitter} object.
// RTN4a, RTN4e, RTN4g
// ConnectionEventEmitter embeds an [ably.ConnectionEventEmitter] object (RTN4a, RTN4e, RTN4g).
ConnectionEventEmitter

// **CANONICAL**
// The current [ConnectionState]{@link ConnectionState} of the connection.
// RTN4d
// state is the current [ably.ConnectionState] of the connection (RTN4d).
state ConnectionState

// **CANONICAL**
// An [ErrorInfo]{@link ErrorInfo} object describing the last error received if a connection failure occurs.
// RTN14a
// errorReason is an [ably.ErrorInfo] object describing the last error received if
// a connection failure occurs (RTN14a).
errorReason *ErrorInfo

internalEmitter ConnectionEventEmitter

// **CANONICAL**
// A unique public identifier for this connection, used to identify this member.
// RTN8
// id is a unique public identifier for this connection, used to identify this member (RTN8).
id string

// **CANONICAL**
// A unique private connection key used to recover or resume a connection, assigned by Ably. When recovering a connection explicitly, the recoveryKey is used in the recover client options as it contains both the key and the last message serial. This private connection key can also be used by other REST clients to publish on behalf of this client. See the publishing over REST on behalf of a realtime client docs for more info.
// RTN9
// key is a unique private connection key used to recover or resume a connection, assigned by Ably.
// When recovering a connection explicitly, the recoveryKey is used in the recover client options as
// it contains both the key and the last message serial. This private connection key can also be used by
// other REST clients to publish on behalf of this client. See the publishing over REST on behalf of
// a realtime client docs for more info (RTN9).
key string

// **CANONICAL**
// The serial number of the last message to be received on this connection, used automatically by the library when recovering or resuming a connection. When recovering a connection explicitly, the recoveryKey is used in the recover client options as it contains both the key and the last message serial.
// RTN10
// serial is the serial number of the last message to be received on this connection, used automatically by
// the library when recovering or resuming a connection. When recovering a connection explicitly, the recoveryKey
// is used in the recover client options as it contains both the key and the last message serial (RTN10).
serial *int64
msgSerial int64
connStateTTL durationFromMsecs
Expand Down Expand Up @@ -186,19 +178,16 @@ func (c *Connection) Connect() {
}()
}

// **LEGACY**
// Close attempts to move the connection to the CLOSED state, if it can and if
// it isn't already.
// **CANONICAL**
// Causes the connection to close, entering the [CLOSING]{@link ConnectionState#CLOSING} state. Once closed, the library does not attempt to re-establish the connection without an explicit call to [connect()]{@link Connection#connect}.
// RTN12
// Close causes the connection to close, entering the [ably.ConnectionStateClosing] state.
// Once connection state is [ably.ConnectionStateClosed], the library does not attempt to re-establish
// the connection without an explicit call to Connection.Connect (RTN12).
func (c *Connection) Close() {
c.close()
}

// **CANONICAL**
// Explicitly calling connect() is unnecessary unless the autoConnect attribute of the [ClientOptions]{@link ClientOptions} object is false. Unless already connected or connecting, this method causes the connection to open, entering the [CONNECTING]{@link ConnectionState#CONNECTING} state.
// RTC1b, RTN3, RTN11
// Connect calling this method is needed only if the NoConnect attribute of the clientOptions object is true.
// If not in connecting or connected state, this method causes the connection to open, entering the
// [ably.ConnectionStateConnecting] state (RTC1b, RTN3, RTN11).
func (c *Connection) connect(arg connArgs) (result, error) {
c.mtx.Lock()
arg.mode = c.getMode()
Expand Down Expand Up @@ -533,7 +522,7 @@ type ConnectionEventEmitter struct {

// On registers an event handler for connection events of a specific kind.
//
// See package-level documentation on Event Emitter for details.
// See package-level documentation => [ably] Event Emitters for more details.
func (em ConnectionEventEmitter) On(e ConnectionEvent, handle func(ConnectionStateChange)) (off func()) {
return em.emitter.On(e, func(change emitterData) {
handle(change.(ConnectionStateChange))
Expand All @@ -542,7 +531,7 @@ func (em ConnectionEventEmitter) On(e ConnectionEvent, handle func(ConnectionSta

// OnAll registers an event handler for all connection events.
//
// See package-level documentation on Event Emitter for details.
// See package-level documentation => [ably] Event Emitters for more details.
func (em ConnectionEventEmitter) OnAll(handle func(ConnectionStateChange)) (off func()) {
return em.emitter.OnAll(func(change emitterData) {
handle(change.(ConnectionStateChange))
Expand All @@ -551,7 +540,7 @@ func (em ConnectionEventEmitter) OnAll(handle func(ConnectionStateChange)) (off

// Once registers an one-off event handler for connection events of a specific kind.
//
// See package-level documentation on Event Emitter for details.
// See package-level documentation => [ably] Event Emitters for more details.
func (em ConnectionEventEmitter) Once(e ConnectionEvent, handle func(ConnectionStateChange)) (off func()) {
return em.emitter.Once(e, func(change emitterData) {
handle(change.(ConnectionStateChange))
Expand All @@ -560,7 +549,7 @@ func (em ConnectionEventEmitter) Once(e ConnectionEvent, handle func(ConnectionS

// OnceAll registers an one-off event handler for all connection events.
//
// See package-level documentation on Event Emitter for details.
// See package-level documentation => [ably] Event Emitters for more details.
func (em ConnectionEventEmitter) OnceAll(handle func(ConnectionStateChange)) (off func()) {
return em.emitter.OnceAll(func(change emitterData) {
handle(change.(ConnectionStateChange))
Expand All @@ -569,14 +558,14 @@ func (em ConnectionEventEmitter) OnceAll(handle func(ConnectionStateChange)) (of

// Off deregisters event handlers for connection events of a specific kind.
//
// See package-level documentation on Event Emitter for details.
// See package-level documentation => [ably] Event Emitters for more details.
func (em ConnectionEventEmitter) Off(e ConnectionEvent) {
em.emitter.Off(e)
}

// OffAll deregisters all event handlers.
//
// See package-level documentation on Event Emitter for details.
// See package-level documentation => [ably] Event Emitters for more details.
func (em ConnectionEventEmitter) OffAll() {
em.emitter.OffAll()
}
Expand Down

0 comments on commit f7779b5

Please sign in to comment.