Class: Prosody::Context

Inherits:
Object
  • Object
show all
Defined in:
lib/prosody/native_stubs.rb

Overview

Represents the context of a Kafka message, providing metadata and control capabilities for message handling.

Instances of this class are created by the native code and passed to your EventHandler’s #on_message method.

See Also:

  • for implementation

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Context

Returns a new instance of Context.

Raises:

  • (NotImplementedError) 


37
38
39
 
# File 'lib/prosody/native_stubs.rb', line 37

def initialize
  raise NotImplementedError, "This class is implemented natively in Rust"
end

Instance Method Details

#clear_and_schedule(time) ⇒ void

This method returns an undefined value.

Clears all scheduled timers and schedules a new one at the specified time.

This is equivalent to calling clear_scheduled followed by schedule, but performed atomically.

Examples:

Replacing all timers with a new one

def on_message(context, message)
  # Clear any existing timers and schedule a new one
  context.clear_and_schedule(Time.now + 60)
end

Parameters:

  • time (Time) —

    When the new timer should fire

Raises:

  • (ArgumentError) —

    If the time is invalid or outside the supported range

  • (RuntimeError) —

    If timer operations fail



121
122
123
 
# File 'lib/prosody/native_stubs.rb', line 121

def clear_and_schedule(time)
  raise NotImplementedError, "This method is implemented natively in Rust"
end

#clear_scheduled ⇒ void

This method returns an undefined value.

Clears all scheduled timers.

After calling this method, no timers will be scheduled to fire for this message context.

Examples:

Canceling all timers

def on_message(context, message)
  context.clear_scheduled
end

Raises:

  • (RuntimeError) —

    If clearing timers fails



159
160
161
 
# File 'lib/prosody/native_stubs.rb', line 159

def clear_scheduled
  raise NotImplementedError, "This method is implemented natively in Rust"
end

#on_cancel ⇒ void

This method returns an undefined value.

Blocks until cancellation is signaled.

Cancellation includes message-level cancellation (e.g., handler timeout) and partition shutdown. During shutdown, cancellation is delayed until near the end of the shutdown timeout to allow in-flight work to complete. This method is useful for long-running handlers that need to wait for external events while remaining responsive to cancellation.

Examples:

Waiting for cancellation

def on_message(context, message)
  # Do some work, then wait for cancellation
  context.on_cancel
end

Raises:

  • (NotImplementedError) 


78
79
80
 
# File 'lib/prosody/native_stubs.rb', line 78

def on_cancel
  raise NotImplementedError, "This method is implemented natively in Rust"
end

#schedule(time) ⇒ void

This method returns an undefined value.

Schedules a timer to fire at the specified time.

Timers allow you to delay execution or implement timeout behavior within your message handlers. When a timer fires, your handler’s #on_timer method will be called with the timer object.

Examples:

Scheduling a delayed action

def on_message(context, message)
  # Schedule a timer to fire in 30 seconds
  context.schedule(Time.now + 30)
end

def on_timer(context, timer)
  puts "Timer fired for key: #{timer.key}"
end

Parameters:

  • time (Time) —

    When the timer should fire

Raises:

  • (ArgumentError) —

    If the time is invalid or outside the supported range (1970-2106)

  • (RuntimeError) —

    If timer scheduling fails



102
103
104
 
# File 'lib/prosody/native_stubs.rb', line 102

def schedule(time)
  raise NotImplementedError, "This method is implemented natively in Rust"
end

#scheduled ⇒ Array<Time>

Returns all currently scheduled timer times.

The returned array contains Time objects representing when each scheduled timer will fire. The array may be empty if no timers are scheduled.

Examples:

Checking scheduled timers

def on_message(context, message)
  scheduled_times = context.scheduled
  puts "#{scheduled_times.length} timers scheduled"
  scheduled_times.each do |time|
    puts "Timer will fire at: #{time}"
  end
end

Returns:

  • (Array<Time>) —

    Array of scheduled timer times

Raises:

  • (RuntimeError) —

    If retrieving scheduled times fails



179
180
181
 
# File 'lib/prosody/native_stubs.rb', line 179

def scheduled
  raise NotImplementedError, "This method is implemented natively in Rust"
end

#should_cancel? ⇒ Boolean

Checks if cancellation has been requested.

This method can be called within message handlers to detect when the handler should exit. Cancellation includes message-level cancellation (e.g., handler timeout) and partition shutdown. During shutdown, cancellation is delayed until near the end of the shutdown timeout to allow in-flight work to complete.

Examples:

Checking for cancellation in a loop

def on_message(context, message)
  items = message.payload["items"]
  items.each do |item|
    return if context.should_cancel?
    process_item(item)
  end
end

Returns:

  • (Boolean) —

    true if cancellation has been requested, false otherwise

Raises:

  • (NotImplementedError) 


59
60
61
 
# File 'lib/prosody/native_stubs.rb', line 59

def should_cancel?
  raise NotImplementedError, "This method is implemented natively in Rust"
end

#unschedule(time) ⇒ void

This method returns an undefined value.

Unschedules a timer that was scheduled for the specified time.

If multiple timers were scheduled for the same time, this will remove one of them. If no timer exists for the specified time, this method does nothing.

Examples:

Canceling a specific timer

def on_message(context, message)
  timer_time = Time.now + 30
  context.schedule(timer_time)

  # Later, cancel that specific timer
  context.unschedule(timer_time)
end

Parameters:

  • time (Time) —

    The time for which to unschedule the timer

Raises:

  • (ArgumentError) —

    If the time is invalid

  • (RuntimeError) —

    If timer unscheduling fails



143
144
145
 
# File 'lib/prosody/native_stubs.rb', line 143

def unschedule(time)
  raise NotImplementedError, "This method is implemented natively in Rust"
end