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

Stop monitoring the given reference.

@spec join() :: :ok

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

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

Join the given process to the consumers of the current bot.

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. If you wish to stop listening to events, call leave/1.

If joining the consumer groups of multiple bots, use the bot_options field of the Nostrum.Struct.WSState.t/0 sent with gateway events (see Nostrum.Consumer.event/0) to determine which bot the current event came from.

Example

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

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

  def command(%Message{author: %User{id: author_id}}) do
    Message.create(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"}, _}} ->
        Message.create(msg, "The large burger menu is coming.")
    after
      5_000 ->
        Message.create(msg, "Too slow!")
    end
  end
end

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

@spec leave(pid() | [pid()]) :: :ok | :not_joined

Leave the given process or processes from the current bot's consumer group.

Useful if you wish to stop listening for events after a while.

@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.