Alllow using custom GlobalProfiler instance with puffin_http::Server

[v0x0g]

Checklist

• I have read the Contributor Guide
• I have read and agree to the Code of Conduct
• I have added a description of my changes and why I'd like them included in the section below

Changes

Allow puffin_http::Server to use a custom puffin::GlobalProfiler instance.

• Add a new constructor function Server::new_custom()
• It takes in two function pointers to call when adding/removing the Server as a Sink.
• These can be changed to add to a GlobalProfiler instance that isn't the default instance returned by GlobalProfiler::lock()
• Existing Server::new() now simply wraps this new function around the default GlobalProfiler::lock() function, so behaviour is the same
• Add extensive documentation including working examples and a helpful macro

Example Usage

Here's a video of me using it to profile my project rayna.

On the left we have my app, with the render profiler running top right and the ui profiler running bottom right. Note that this is one app process, but it has two separate puffin_http::Server instances. Note how in the video these profilers are sending frames completely independently, but for the same process.

Apologies for the compression, it doesn't seem to like my noisy images...

2024-05-18_00-33-32.mp4

[v0x0g]

Example Code

I used a macro for this, but it generates something very similar to the following:

pub mod main {
    use std::sync::{Mutex, MutexGuard};
    use once_cell::sync::Lazy;
    use puffin_http::Server;
    use puffin::{
        FrameSink, FrameSinkId, StreamInfoRef, ScopeDetails,
        ThreadProfiler, ThreadInfo, GlobalProfiler,
    };
    
    
    #[doc = concat!( "The address to bind the ", stringify!( main ), " thread profilers' server to" )]
    pub const ADDR: &'static str = concat!( "127.0.0.1:", 8587 );
    
    
    ///   Installs the server's sink into the custom profiler 
    #[doc(hidden)]
    fn install(sink: FrameSink) -> FrameSinkId {
        self::lock().add_sink(sink)
    }
    
    
    ///   Drops the server's sink and removes from profiler 
    #[doc(hidden)]
    fn drop(id: FrameSinkId) {
        self::lock().remove_sink(id);
    }
    
    
    #[doc = concat!( "The instance of the ", stringify!( main ), " thread profilers' server" )]
    pub static SERVER: Lazy<Mutex<Server>> = Lazy::new(||
        Mutex::new(
            Server::new_custom(self::ADDR, self::install, self::drop).expect(&format!("{} puffin_http server failed to start", stringify!( main )))
        )
    });
    
    
    #[doc = concat!( "A custom reporter for the ", std::stringify!( main ), " thread reporter" )]
    pub fn reporter(info: ThreadInfo, details: &[ScopeDetails], stream: &StreamInfoRef<'_>) {
        self::lock().report(info, details, stream)
    }
    
    
    #[doc = concat!( "Accessor for the ", stringify!( main ), " thread reporter" )]
    pub fn lock() -> MutexGuard<'static, GlobalProfiler> {
        static PROFILER: Lazy<Mutex<GlobalProfiler>> = Lazy::new(Default::default);
        PROFILER.lock().expect(&format!("poisoned std::sync::mutex for {}", stringify!( main )))
    }
    
    
    #[doc = concat!( "Initialises the ", stringify!( main ), " thread reporter and server.\
            Call this on each different thread you want to register with this profiler" )]
    pub fn init_thread() {
        std::mem::drop(self::SERVER.lock());
        ThreadProfiler::initialize(::puffin::now_ns, self::reporter);
    }
}

Once I have the server objects generated (like above), I can use them like so:

debug!(target: MAIN, "init puffin");
// Profiling is pretty low-cost
trace!(target: MAIN, "enable profiling");
puffin::set_scopes_on(true);
trace!(target: MAIN, "init main profiler");
profiler::main::init_thread();
// Special handling so the 'default' profiler passes on to our custom profiler
// In this case, we already overrode the ThreadProfiler for "main" using `main_profiler_init()`,
// So the events are already going to our custom profiler, but egui still calls `new_frame()` on the
// global profiler. So here, pass along the `new_frame()`s to the custom one
puffin::GlobalProfiler::lock().add_sink(Box::new(|_| profiler::main::lock().new_frame();));

This now redirects all the profiling events for whichever thread it was run in (in this case the UI thread), which get send to the profiler::main::SERVER instance. I can connect to this on 127.0.0.1:8587, while having another connection for my worker threads, which update completely independently of the main UI thread.

[v0x0g]

This needs to be made public so that GlobalProfiler::report() can be called by our custom ThreadProfiler.reporter that we assign.

[v0x0g]

These deps are here so that the example code can be tested in the docs for Server::new_custom().

We could modify the examples if needed to remove this, but it would be a decent amount of work

[v0x0g]

@emilk @TimonPost Any update on these?

[emilk]

Very cool!