Class: PatientHttp::ProcessorObserver

Inherits:
Object
  • Object
show all
Defined in:
lib/patient_http/processor_observer.rb

Overview

Interface for observing request processing. A process observer can be registered with a Processor and receive events as requests are processed. Observers should be lightweight and not do processing other than recording metrics or similar.

Hooks run on different threads depending on where the event originates:

  • request_enqueued, request_rejected: the thread calling Processor#enqueue (usually an application thread), and the reactor thread for each task created to follow a redirect. Work done in these hooks blocks the reactor for redirected requests, so keep it off the critical path or accept the delay it adds to every other in-flight request
  • capacity_exceeded: the thread calling Processor#enqueue (usually an application thread)
  • request_start: the reactor thread
  • request_end, request_error, completion_failed: a completion worker thread (request_end also fires on the reactor thread for followed redirects, and on the stopping thread for shutdown re-enqueues)
  • request_requeued: the stopping thread or the reactor thread
  • start, stop: the thread calling Processor#start / Processor#stop

Observers must be thread-safe. Hooks are called from several threads, and the completion-time hooks run on any of the completion worker threads, so two of them can run at the same time and in an order unrelated to the order the requests completed. Guard any counter or buffer an observer shares between calls. Setting completion_threads to 1 serializes the completion-time hooks but does not serialize them against the hooks that fire on other threads.

Instance Method Summary collapse

Instance Method Details

#capacity_exceeded ⇒ void

This method returns an undefined value.

Called when a request cannot be enqueued because the processor is at capacity.



46
47
 
# File 'lib/patient_http/processor_observer.rb', line 46

def capacity_exceeded
end

#completion_failed(request_task, error) ⇒ void

This method returns an undefined value.

Called when a finished result could not be delivered to the task handler after all retries. request_end is NOT sent for the task, so durable tracking set up in request_enqueued stays in place and an external recovery process (e.g. an orphan collector) can re-enqueue the request.

Parameters:

  • request_task (RequestTask) —

    the request task whose result was not delivered

  • error (StandardError) —

    the delivery failure



113
114
 
# File 'lib/patient_http/processor_observer.rb', line 113

def completion_failed(request_task, error)
end

#request_end(request_task) ⇒ void

This method returns an undefined value.

Called when a request finishes processing.

Parameters:

  • request_task (RequestTask) —

    the request task that ended



95
96
 
# File 'lib/patient_http/processor_observer.rb', line 95

def request_end(request_task)
end

#request_enqueued(request_task) ⇒ void

This method returns an undefined value.

Called when a request task is handed to the processor, before the task is visible to the reactor. The notification is guaranteed to arrive before request_start for the task, so observers can set up durable tracking (e.g. a crash-recovery registry entry) with no risk that the task completes first. If the processor does not accept the task, request_rejected is sent afterward. Unlike other notifications, an error raised here propagates from Processor#enqueue and rejects the task, so a failed tracking setup does not let the task be accepted as if it were durable.

Parameters:

  • request_task (RequestTask) —

    the request task that was enqueued



61
62
 
# File 'lib/patient_http/processor_observer.rb', line 61

def request_enqueued(request_task)
end

#request_error(error) ⇒ void

This method returns an undefined value.

Called when a request encounters an error.

Parameters:

  • error (StandardError) —

    the error that occurred



102
103
 
# File 'lib/patient_http/processor_observer.rb', line 102

def request_error(error)
end

#request_rejected(request_task) ⇒ void

This method returns an undefined value.

Called when a request task announced with request_enqueued was not accepted by the processor (not running or at capacity). Observers should tear down anything they set up in request_enqueued; the caller owns the request again once this is sent.

Parameters:

  • request_task (RequestTask) —

    the request task that was rejected



71
72
 
# File 'lib/patient_http/processor_observer.rb', line 71

def request_rejected(request_task)
end

#request_requeued(request_task) ⇒ void

This method returns an undefined value.

Called when an incomplete request task was re-enqueued through its task handler (processor shutdown or reactor failure). The task handler's job system owns the request again once this is sent, so observers should tear down any durable tracking for the task.

Parameters:

  • request_task (RequestTask) —

    the request task that was re-enqueued



81
82
 
# File 'lib/patient_http/processor_observer.rb', line 81

def request_requeued(request_task)
end

#request_start(request_task) ⇒ void

This method returns an undefined value.

Called when a request starts processing.

Parameters:

  • request_task (RequestTask) —

    the request task that started



88
89
 
# File 'lib/patient_http/processor_observer.rb', line 88

def request_start(request_task)
end

#start ⇒ void

This method returns an undefined value.

Called when the processor starts.



34
35
 
# File 'lib/patient_http/processor_observer.rb', line 34

def start
end

#stop ⇒ void

This method returns an undefined value.

Called when the processor stops.



40
41
 
# File 'lib/patient_http/processor_observer.rb', line 40

def stop
end