add docs about accessing default handlers

LLNL · Mar 11, 2021 · 340575f · 340575f
1 parent 777de5d
commit 340575f
Show file tree

Hide file tree

Showing 2 changed files with 36 additions and 0 deletions.
diff --git a/src/docs/sphinx/tutorial_cpp_errors.rst b/src/docs/sphinx/tutorial_cpp_errors.rst
@@ -80,3 +80,20 @@ The default handlers are part of the conduit::utils interface, so you can restor
    :language: cpp
    :dedent: 4
 
+Accessing Current Handlers
+--------------------------------
+
+You can access the currently active handlers using the `conduit::utils::info_handler()`,
+`conduit::utils::warning_handler()`, and `conduit::utils::error_handler()` methods.
+Here is an example that shows how to save the current handlers, temporarily restore
+the default handlers, execute an operation, and finally restore the saved handlers:
+
+.. literalinclude:: ../../tests/docs/t_conduit_docs_tutorial_errors.cpp
+   :start-after: BEGIN_EXAMPLE("error_handlers_current_push_pop")
+   :end-before:  END_EXAMPLE("error_handlers_current_push_pop")
+   :language: cpp
+   :dedent: 4
+
+
+
+
diff --git a/src/tests/docs/t_conduit_docs_tutorial_errors.cpp b/src/tests/docs/t_conduit_docs_tutorial_errors.cpp
@@ -100,6 +100,25 @@ TEST(conduit_tutorial, error_handlers)
     conduit::utils::set_warning_handler(conduit::utils::default_warning_handler);
     conduit::utils::set_error_handler(conduit::utils::default_error_handler);
     END_EXAMPLE("error_handlers_reset");
+
+    BEGIN_EXAMPLE("error_handlers_current_push_pop");
+    // store current handlers
+    conduit::utils::conduit_info_handler    on_info  = conduit::utils::info_handler();
+    conduit::utils::conduit_warning_handler on_warn  = conduit::utils::warning_handler();
+    conduit::utils::conduit_error_handler   on_error = conduit::utils::error_handler();
+
+    // temporarily restore default handlers
+    conduit::utils::set_info_handler(conduit::utils::default_info_handler);
+    conduit::utils::set_warning_handler(conduit::utils::default_warning_handler);
+    conduit::utils::set_error_handler(conduit::utils::default_error_handler);
+
+    // do something exciting ...
+
+    // done with excitement, reset to previously saved handlers
+    conduit::utils::set_info_handler(on_info);
+    conduit::utils::set_warning_handler(on_warn);
+    conduit::utils::set_error_handler(on_error);
+    END_EXAMPLE("error_handlers_current_push_pop");
 }