@spec demonitor(reference()) :: :ok | false

Stop monitoring the given reference.

@spec dispatch([Nostrum.Consumer.event(), ...]) :: :ok

@spec dispatch(Nostrum.Consumer.event()) :: :ok

Dispatch the given event(s) to all consumers.

This is called by nostrum internally, you likely won't need to call this manually.

@spec join() :: :ok

Equivalent to ConsumerGroup.join(self()). See join/1.

@spec join(pid()) :: :ok

Join the given process to the consumers.

If no process is given, joins the current process to the consumers. This can be used for subscribing to gateway events and awaiting them inline.

After the process has joined, it will receive any events sent by nostrum's gateway dispatch. These events are sent as messages {:event, t:Consumer.Event.t/0}. The given pid is automatically unsubscribed when it terminates.

Note that there is currently no filtering done. If the gateway sends a lot of messages and the event subscriber does not terminate swiftly, its message queue will keep growing.

Example

The following example illustrates how to use this to implement inline event awaiting:

defmodule MyBot.Command
  alias Nostrum.Api
  alias Nostrum.ConsumerGroup
  alias Nostrum.Struct.Message
  alias Nostrum.Struct.User

  def command(%Message{author: %User{id: author_id}}) do
    Api.create_message!(msg, "Reply 'y' in 5 seconds to confirm ordering a large burger menu.")
    ConsumerGroup.join()
    receive do
      {:event, {:MESSAGE_CREATE, %Message{author: %User{id: author_id}, content: "y"}, _}} ->
        Api.create_message!(msg, "The large burger menu is coming.")
    after
      5_000 ->
        Api.create_message!(msg, "Too slow!")
    end
  end
end

@spec monitor() :: {reference(), [pid()]}

Monitor the consumer group for changes.

Return the initial state of the group on first call. Further updates are delivered as messages to the calling process, see :pg.monitor/2 for details. The returned reference/0 must be saved for later calls to demonitor/1.