Solution: Support manual job triggering (#459)

* Seems that run_job is working. Needs a test

* scheduler run_job tests and some docs

* changes requested in PR 459

Author: ericdude4

lib/quantum.ex

@@ -148,6 +148,11 @@ defmodule Quantum do
   """
   @callback activate_job(GenStage.stage(), atom) :: :ok
 
+  @doc """
+  Runs a job by name once
+  """
+  @callback run_job(GenStage.stage(), atom) :: :ok
+
   @doc """
   Resolves a job by name
   """
@@ -289,6 +294,12 @@ defmodule Quantum do
         GenStage.cast(server, {:change_state, name, :active})
       end
 
+      @impl behaviour
+      def run_job(server \\ __job_broadcaster__(), name)
+          when is_atom(name) or is_reference(name) do
+        GenStage.cast(server, {:run_job, name})
+      end
+
       @impl behaviour
       def find_job(server \\ __job_broadcaster__(), name)
           when is_atom(name) or is_reference(name) do

lib/quantum/execution_broadcaster.ex

@@ -121,6 +121,18 @@ defmodule Quantum.ExecutionBroadcaster do
     {[], %{state | uninitialized_jobs: [job | uninitialized_jobs]}}
   end
 
+  def handle_event(
+        {:run, %Job{name: name} = job},
+        %State{debug_logging: debug_logging} = state
+      ) do
+    debug_logging &&
+      Logger.debug(fn ->
+        "[#{inspect(Node.self())}][#{__MODULE__}] Running job #{inspect(name)} once"
+      end)
+
+    {[%ExecuteEvent{job: job}], state}
+  end
+
   def handle_event(
         {:remove, name},
         %State{

lib/quantum/job_broadcaster.ex

@@ -300,6 +300,27 @@ defmodule Quantum.JobBroadcaster do
     end
   end
 
+  def handle_cast(
+        {:run_job, name},
+        %State{
+          jobs: jobs,
+          debug_logging: debug_logging
+        } = state
+      ) do
+    debug_logging &&
+      Logger.debug(fn ->
+        "[#{inspect(Node.self())}][#{__MODULE__}] Running job #{inspect(name)} once"
+      end)
+
+    case Map.fetch(jobs, name) do
+      :error ->
+        {:noreply, [], state}
+
+      {:ok, job} ->
+        {:noreply, [{:run, job}], state}
+    end
+  end
+
   def handle_cast(
         :delete_all,
         %State{

pages/runtime.md

@@ -30,6 +30,11 @@ Activate an inactive job:
 YourApp.Scheduler.activate_job(:ticker)
 ```
 
+Run a job once outside of normal schedule:
+```elixir
+YourApp.Scheduler.run_job(:ticker)
+```
+
 Find a job:
 ```elixir
 YourApp.Scheduler.find_job(:ticker)

test/quantum/execution_broadcaster_test.exs

@@ -77,6 +77,14 @@ defmodule Quantum.ExecutionBroadcasterTest do
       end)
     end
 
+    test "run_job triggers job to run once", %{producer: producer} do
+      job = TestScheduler.new_job()
+
+      TestProducer.send(producer, {:run, job})
+
+      assert_receive {:received, %ExecuteEvent{job: ^job}}
+    end
+
     test "normal schedule triggers once per second", %{producer: producer} do
       job =
         TestScheduler.new_job()

test/quantum/job_broadcaster_test.exs

@@ -213,6 +213,19 @@ defmodule Quantum.JobBroadcasterTest do
              end) =~ "Adding job #Reference"
     end
 
+    @tag listen_storage: true
+    test "run", %{broadcaster: broadcaster, active_job: active_job} do
+      test_id = "run-job-handler"
+
+      :ok = attach_telemetry(:run, test_id, self())
+
+      TestScheduler.add_job(broadcaster, active_job)
+      TestScheduler.run_job(broadcaster, active_job.name)
+
+      assert_receive {:received, {:add, ^active_job}}
+      assert_receive {:received, {:run, ^active_job}}
+    end
+
     @tag listen_storage: true
     test "inactive", %{broadcaster: broadcaster, inactive_job: inactive_job} do
       test_id = "add-inactive-job-handler"