From e4c59d08005c61c048e957369bbe0c579ec3deb1 Mon Sep 17 00:00:00 2001
From: Isaac Harris-Holt <isaac@harris-holt.com>
Date: Fri, 25 Oct 2024 20:53:45 +0100
Subject: [PATCH] add run_once

---
 CHANGELOG.md       |  4 ++++
 README.md          | 23 +++++++++++++++++++++++
 gleam.toml         |  2 +-
 src/barnacle.gleam |  9 +++++++++
 4 files changed, 37 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1758f5b..2e63cad 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,9 @@
 # Changelog
 
+## v1.1.0 - 2024-10-25
+
+- Add `run_once` function for when polling is not needed.
+
 ## v1.0.0 - 2024-10-21
 
 - Initial release with `local_epmd`, `epmd` and `dns` strategies, as well as support
diff --git a/README.md b/README.md
index 61f0bb5..d4133d2 100644
--- a/README.md
+++ b/README.md
@@ -89,6 +89,29 @@ pub fn main() {
 }
 ```
 
+### Run the refresh function once
+
+If you don't need any sort of polling, or want to manage your the refresh lifecycle
+yourself, you can call the `run_once` function to run the refresh function a single
+time.
+
+In this case, most of the configuration options will be ignored.
+
+```gleam
+import barnacle
+
+pub fn main() {
+  // Configure your Barnacle
+  let barnacle =
+    barnacle.local_epmd()
+
+  // Run the refresh function once
+  barnacle.run_once(barnacle)
+
+  // Continue your program...
+}
+```
+
 ## Strategies
 
 Barnacle ships with a few built-in strategies, but you can also supply your own by
diff --git a/gleam.toml b/gleam.toml
index 60e574d..5fd2e7a 100644
--- a/gleam.toml
+++ b/gleam.toml
@@ -1,5 +1,5 @@
 name = "barnacle"
-version = "1.0.0"
+version = "1.1.0"
 
 description = "Self-healing clusters for Gleam applications on the BEAM!"
 licences = ["MIT"]
diff --git a/src/barnacle.gleam b/src/barnacle.gleam
index ed55e08..166629c 100644
--- a/src/barnacle.gleam
+++ b/src/barnacle.gleam
@@ -257,6 +257,15 @@ pub fn child_spec(
   })
 }
 
+/// Run the refresh function once only. This will not start the actor, and will
+/// not do any polling.
+///
+/// In this case, most configuration options are irrelevant and will be ignored.
+pub fn run_once(barnacle: Barnacle(error)) {
+  barnacle
+  |> refresh_nodes
+}
+
 /// Refresh a barnacle actor. This will attempt to connect to new nodes, and
 /// disconnect from nodes that are no longer available.
 ///