README
¶
QuickIGo 
This if the official go client for QuickIO.
Check out the docs for full examples and usage.
License
MIT
Documentation
¶
Overview ¶
Package quickigo implements a QuickIO client in Go.
Index ¶
- Constants
- type Cb
- type QuickIGo
- func (qio *QuickIGo) Close()
- func (qio *QuickIGo) Off(evPath string, ch chan<- Cb, ctx interface{})
- func (qio *QuickIGo) On(evPath string, data interface{}, ch chan<- Cb, ctx interface{})
- func (qio *QuickIGo) One(evPath string, data interface{}, ch chan<- Cb, ctx interface{})
- func (qio *QuickIGo) Open()
- func (qio *QuickIGo) Send(evPath string, data interface{}, ch chan<- Cb, ctx interface{})
- Bugs
Examples ¶
Constants ¶
const ( // CodeBad indicates that the given data was invalid in some way CodeBad = 400 // CodeDisconnected indicates that the connection was lost CodeDisconnected = -1 // CodeInProgress indicates that an operation is still pending CodeInProgress = 202 // CodeNotFound indicates that the event doesn't exist CodeNotFound = 404 // CodeOk indicates everything went right CodeOk = 200 // CodeUnauth indicates you're not authorized to do that CodeUnauth = 401 // EvClose is the event path for close events EvClose = "/close" // EvError is the event path for error events EvError = "/error" // EvOpen is the event path for open events EvOpen = "/open" )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Cb ¶
type Cb struct {
Data interface{} // Data from the server
Code int // Error code, only set for callbacks and subscribe errors
Err error // A human-readable error, if code != 200
Ctx interface{} // Passed-in context
// contains filtered or unexported fields
}
Cb is a standard callback issued from all events.
type QuickIGo ¶
type QuickIGo struct {
// contains filtered or unexported fields
}
QuickIGo is the client object.
This object's lifecycle is controlled by the garbage collector; there are a few pitfalls to be aware of:
The lifecycle is of the QuickIGo object is controlled by the garbage collector. When there are no more references, everything around it is shut down. The following code is not guaranteed to work:
func getData() interface{} {
ch := make(chan Cb)
qio := New(...)
qio.On("/test", nil, ch, nil)
cb := <-ch // Might never receive anything
return cb.Data
}
Since the qio object isn't referenced after On(), it might be garbage collected before the channel ever receives a message. The simple solution is to either (0) store a reference to the object in something that will be alive or (1) use the object after waiting on the channel; for example:
func getData() interface{} {
ch := make(chan Cb)
qio := New(...)
qio.On("/test", nil, ch, nil)
cb := <-ch
qio.Close() // Going to be destroyed anyway
return cb.Data
}
BUG(astone): This client currently only connects on WebSocket and does not fall back to HTTP.
func New ¶
New creates a new QuickIO client.
Be sure to read through the common pitfalls on the QuickIGo struct.
Example ¶
qio := New(TestServer)
ch := make(chan Cb)
opened := make(chan Cb)
closed := make(chan Cb)
error := make(chan Cb)
qio.On(EvOpen, nil, opened, nil)
qio.On(EvClose, nil, closed, nil)
qio.On(EvError, nil, error, nil)
qio.Open()
for i := 0; i < 2; i++ {
select {
case <-opened:
fmt.Println("connection established")
qio.Close()
case <-closed:
fmt.Println("lost connection")
case cb := <-error:
fmt.Println("connection error:", cb.Err)
}
}
qio.Open()
<-opened
ctx := "some data"
qio.Send("/clienttest/echo", "echo data", ch, ctx)
cb := <-ch
fmt.Println(cb.Data, ":", cb.Ctx)
// Check if the server wanted a callback
if cb.CanReply() {
cb.Reply("some more data", ch, ctx)
cb = <-ch
fmt.Println(cb.Data)
}
qio.Close()
// At this point, it's completely safe to call On()/Off()/Send();
// any relevant state will be sent to the server when a connection
// is reestablished.
Output: connection established lost connection echo data : some data some more data
func (*QuickIGo) Close ¶
func (qio *QuickIGo) Close()
Close disconnects from the QuickIO cluster, unless already disconnected.
func (*QuickIGo) Off ¶
Off removes a channel from a subscription. A nil channel removes all subscriptions.
func (*QuickIGo) On ¶
On adds a channel to the given event path to receive data on when the server fires an event.
When subscribing to an event, it's also possible to send some data along with the subscription so that the server knows how to handle it. If data is nil, no extra data is sent.
Since a single channel may be used for multiple events, you may also include a ctx value that will be included with any callbacks sent to the channel.
func (*QuickIGo) One ¶
One functions in the same was as On(), but the given channel will only ever recieve 1 message before being removed from the subscription
Notes ¶
Bugs ¶
This client currently only connects on WebSocket and does not fall back to HTTP.
Source Files