pingora_core/services/
background.rs

1// Copyright 2026 Cloudflare, Inc.
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7// http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15//! The background service
16//!
17//! A [BackgroundService] can be run as part of a Pingora application to add supporting logic that
18//! exists outside of the request/response lifecycle.
19//! Examples might include service discovery (load balancing) and background updates such as
20//! push-style metrics.
21
22use async_trait::async_trait;
23use std::sync::Arc;
24
25use super::{ServiceReadyNotifier, ServiceWithDependents};
26#[cfg(unix)]
27use crate::server::ListenFds;
28use crate::server::ShutdownWatch;
29
30/// The background service interface
31///
32/// You can implement a background service with or without the ready notifier,
33/// but you shouldn't implement both. Under the hood, the pingora service will
34/// call the `start_with_ready_notifier` function. By default this function will
35/// call the regular `start` function.
36#[async_trait]
37pub trait BackgroundService {
38    /// This function is called when the pingora server tries to start all the
39    /// services. The background service should signal readiness by calling
40    /// `ready_notifier.notify_ready()` once initialization is complete.
41    /// The service can return at anytime or wait for the `shutdown` signal.
42    ///
43    /// By default this method will immediately signal readiness and call
44    /// through to the regular `start` function
45    async fn start_with_ready_notifier(
46        &self,
47        shutdown: ShutdownWatch,
48        ready_notifier: ServiceReadyNotifier,
49    ) {
50        ready_notifier.notify_ready();
51        self.start(shutdown).await;
52    }
53
54    /// This function is called when the pingora server tries to start all the
55    /// services. The background service can return at anytime or wait for the
56    /// `shutdown` signal.
57    async fn start(&self, mut _shutdown: ShutdownWatch) {}
58}
59
60/// A generic type of background service
61pub struct GenBackgroundService<A> {
62    // Name of the service
63    name: String,
64    // Task the service will execute
65    task: Arc<A>,
66    /// The number of threads. Default is 1
67    pub threads: Option<usize>,
68}
69
70impl<A> GenBackgroundService<A> {
71    /// Generates a background service that can run in the pingora runtime
72    pub fn new(name: String, task: Arc<A>) -> Self {
73        Self {
74            name,
75            task,
76            threads: Some(1),
77        }
78    }
79
80    /// Return the task behind [Arc] to be shared other logic.
81    pub fn task(&self) -> Arc<A> {
82        self.task.clone()
83    }
84}
85
86#[async_trait]
87impl<A> ServiceWithDependents for GenBackgroundService<A>
88where
89    A: BackgroundService + Send + Sync + 'static,
90{
91    // Use default start_service implementation which signals ready immediately
92    // and then calls start_service
93
94    async fn start_service(
95        &mut self,
96        #[cfg(unix)] _fds: Option<ListenFds>,
97        shutdown: ShutdownWatch,
98        _listeners_per_fd: usize,
99        ready: ServiceReadyNotifier,
100    ) {
101        self.task.start_with_ready_notifier(shutdown, ready).await;
102    }
103
104    fn name(&self) -> &str {
105        &self.name
106    }
107
108    fn threads(&self) -> Option<usize> {
109        self.threads
110    }
111}
112
113/// Helper function to create a background service with a human readable name
114pub fn background_service<SV>(name: &str, task: SV) -> GenBackgroundService<SV> {
115    GenBackgroundService::new(format!("BG {name}"), Arc::new(task))
116}
pingora_core/services/background.rs

pingora_core/services/
background.rs
