golongpoll: github.com/jcuga/golongpoll Index | Files | Directories

package golongpoll

import "github.com/jcuga/golongpoll"


Package Files

events.go longpoll.go longpoll_deprecated.go priority_queue.go utils.go


const (
    // Magic number to represent 'Forever' in
    // LongpollOptions.EventTimeToLiveSeconds
    FOREVER = -1001

type LongpollManager Uses

type LongpollManager struct {
    SubscriptionHandler func(w http.ResponseWriter, r *http.Request)
    // contains filtered or unexported fields

LongpollManager provides an interface to interact with the internal longpolling pup-sub goroutine.

This allows you to publish events via Publish() If for some reason you want to stop the pub-sub goroutine at any time you can call Shutdown() and all longpolling will be disabled. Note that the pub-sub goroutine will exit on program exit, so for most simple programs, calling Shutdown() is not necessary.

A LongpollManager is created with each subscriptionManager that gets created by calls to manager := StartLongpoll(options) This interface also exposes the HTTP handler that client code can attach to a URL like so:

mux := http.NewServeMux()
mux.HandleFunc("/custom/path/to/events", manager.SubscriptionHandler)

Note, this http handler can be wrapped by another function (try capturing the manager in a closure) to add additional validation, access control, or other functionality on top of the subscription handler.

You can have another http handler publish events by capturing the manager in a closure and calling manager.Publish() from inside a http handler. See the advanced example (examples/advanced/advanced.go)

If for some reason you want multiple goroutines handling different pub-sub channels, you can simply create multiple LongpollManagers.

func CreateCustomManager Uses

func CreateCustomManager(maxTimeoutSeconds, eventBufferSize int,
    loggingEnabled bool) (*LongpollManager, error)

DEPRECATED. Use StartLongpoll or StartLongpoll instead.

func CreateManager Uses

func CreateManager() (*LongpollManager, error)

DEPRECATED. Use StartLongpoll or StartLongpoll instead.

func StartLongpoll Uses

func StartLongpoll(opts Options) (*LongpollManager, error)

Creates a LongpollManager, starts the internal pub-sub goroutine and returns the manager reference which you can use anywhere to Publish() events or attach a URL to the manager's SubscriptionHandler member. This function takes an Options struct that configures the longpoll behavior. If Options.EventTimeToLiveSeconds is omitted, the default is forever.

func (*LongpollManager) Publish Uses

func (m *LongpollManager) Publish(category string, data interface{}) error

Publish an event for a given subscription category. This event can have any arbitrary data that is convert-able to JSON via the standard's json.Marshal() the category param must be a non-empty string no longer than 1024, otherwise you get an error.

func (*LongpollManager) Shutdown Uses

func (m *LongpollManager) Shutdown()

Shutdown allows the internal goroutine that handles the longpull pup-sub to be stopped. This may be useful if you want to turn off longpolling without terminating your program. After a shutdown, you can't call Publish() or get any new results from the SubscriptionHandler. Multiple calls to this function on the same manager will result in a panic.

type Options Uses

type Options struct {
    // Whether or not to print logs about longpolling
    LoggingEnabled bool

    // Max client timeout seconds  to be accepted by the SubscriptionHandler
    // (The 'timeout' HTTP query param).  Defaults to 120.
    MaxLongpollTimeoutSeconds int

    // How many events to buffer per subscriptoin category before discarding
    // oldest events due to buffer being exhausted.  Larger buffer sizes are
    // useful for high volumes of events in the same categories.  But for
    // low-volumes, smaller buffer sizes are more efficient.  Defaults to 250.
    MaxEventBufferSize int

    // How long (seconds) events remain in their respective category's
    // eventBuffer before being deleted. Deletes old events even if buffer has
    // the room.  Useful to save space if you don't need old events.
    // You can use a large MaxEventBufferSize to handle spikes in event volumes
    // in a single category but have a relatively short EventTimeToLiveSeconds
    // value to save space in the more common low-volume case.
    // If you want events to remain in the buffer as long as there is room per
    // MaxEventBufferSize, then use the magic value longpoll.FOREVER here.
    // Defaults to FOREVER.
    EventTimeToLiveSeconds int

    // Whether or not to delete an event as soon as it is retrieved via an
    // HTTP longpoll.  Saves on space if clients only interested in seing an
    // event once and never again.  Meant mostly for scenarios where events
    // act as a sort of notification and each subscription category is assigned
    // to a single client.  As soon as any client(s) pull down this event, it's
    // gone forever.  Notice how multiple clients can get the event if there
    // are multiple clients actively in the middle of a longpoll when a new
    // event occurs.  This event gets sent to all listening clients and then
    // the event skips being placed in a buffer and is gone forever.
    DeleteEventAfterFirstRetrieval bool

Options for LongpollManager that get sent to StartLongpoll(options)


examples/advancedThis is a more advanced example that shows a few more possibilities when using golongpoll.

Package golongpoll imports 11 packages (graph) and is imported by 9 packages. Updated 2020-03-09. Refresh now. Tools for package owners.