Panic on multiple EventLoop instantiation, document why

CHANGELOG.md

@@ -61,6 +61,7 @@ And please only add new entries to the top of this list, right below the `# Unre
 - **Breaking:** `Window::set_cursor_grab` now accepts `CursorGrabMode` to control grabbing behavior.
 - On Wayland, add support for `Window::set_cursor_position`.
 - Fix on macOS `WindowBuilder::with_disallow_hidpi`, setting true or false by the user no matter the SO default value. 
+- `EventLoopBuilder::build` will now panic when the `EventLoop` is being created more than once.
 
 # 0.26.1 (2022-01-05)
 

src/event_loop.rs

@@ -7,11 +7,13 @@
 //!
 //! See the root-level documentation for information on how to create and use an event loop to
 //! handle events.
-use instant::Instant;
 use std::marker::PhantomData;
 use std::ops::Deref;
 use std::{error, fmt};
 
+use instant::Instant;
+use once_cell::sync::OnceCell;
+
 use crate::{event::Event, monitor::MonitorHandle, platform_impl};
 
 /// Provides a way to retrieve events from the system and from the windows that were registered to
@@ -76,8 +78,11 @@ impl<T> EventLoopBuilder<T> {
 
     /// Builds a new event loop.
     ///
-    /// ***For cross-platform compatibility, the [`EventLoop`] must be created on the main thread.***
-    /// Attempting to create the event loop on a different thread will panic. This restriction isn't
+    /// ***For cross-platform compatibility, the [`EventLoop`] must be created on the main thread,
+    /// and only once per application.***
+    ///
+    /// Attempting to create the event loop on a different thread, or multiple event loops in
+    /// the same application, will panic. This restriction isn't
     /// strictly necessary on all platforms, but is imposed to eliminate any nasty surprises when
     /// porting to platforms that require it. `EventLoopBuilderExt::any_thread` functions are exposed
     /// in the relevant [`platform`] module if the target platform supports creating an event loop on
@@ -95,6 +100,10 @@ impl<T> EventLoopBuilder<T> {
     /// [`platform`]: crate::platform
     #[inline]
     pub fn build(&mut self) -> EventLoop<T> {
+        static EVENT_LOOP_CREATED: OnceCell<()> = OnceCell::new();
+        if EVENT_LOOP_CREATED.set(()).is_err() {
+            panic!("Creating EventLoop multiple times is not supported.");
+        }
         // Certain platforms accept a mutable reference in their API.
         #[allow(clippy::unnecessary_mut_passed)]
         EventLoop {