From 61ad0e3de0d7d6018a0856df4a3f2f6684966c41 Mon Sep 17 00:00:00 2001
From: Jonathan Johnson <jon@khonsulabs.com>
Date: Sun, 14 Jul 2024 09:39:07 -0700
Subject: [PATCH] Added LockedBox::try_new

Closes #1
---
 CHANGELOG.md |  7 +++++++
 Cargo.lock   | 10 +++++-----
 Cargo.toml   |  2 +-
 src/lib.rs   | 16 +++++++++++++---
 4 files changed, 26 insertions(+), 9 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6daf31e..8a66ec2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.1.2
+
+### Added
+
+- `LockedBox::try_new` returns `None` if the allocation is too large or
+  an out of memory error.
+
 ## 0.1.1
 
 ### Added
diff --git a/Cargo.lock b/Cargo.lock
index 248c351..adf7809 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -10,9 +10,9 @@ checksum = "baf1de4339761588bc0619e3cbc0120ee582ebb74b53b4efbf79117bd2da40fd"
 
 [[package]]
 name = "getrandom"
-version = "0.2.10"
+version = "0.2.15"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "be4136b2a15dd319360be1c07d9933517ccf0be8f16bf62a3bee4f0d618df427"
+checksum = "c4567c8db10ae91089c99af84c68c38da3ec2f087c3f82960bcdbf3656b6f4d7"
 dependencies = [
  "cfg-if",
  "libc",
@@ -21,13 +21,13 @@ dependencies = [
 
 [[package]]
 name = "libc"
-version = "0.2.147"
+version = "0.2.155"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b4668fb0ea861c1df094127ac5f1da3409a82116a4ba74fca2e58ef927159bb3"
+checksum = "97b3888a4aecf77e811145cadf6eef5901f4782c53886191b2f693f24761847c"
 
 [[package]]
 name = "lockedbox"
-version = "0.1.1"
+version = "0.1.2"
 dependencies = [
  "memsec",
 ]
diff --git a/Cargo.toml b/Cargo.toml
index bc6d21f..23d1f97 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "lockedbox"
-version = "0.1.1"
+version = "0.1.2"
 description = "A Box-like type that prevents paging its contents to disk."
 edition = "2021"
 license = "MIT OR Apache-2.0"
diff --git a/src/lib.rs b/src/lib.rs
index de03cb9..d6df927 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -24,13 +24,23 @@ impl<T> LockedBox<T> {
     ///
     /// # Panics
     ///
-    /// This function panics If `size_of::<T>() >= usize::MAX - 4 * PAGE_SIZE`.
+    /// This function panics if `size_of::<T>() >= usize::MAX - 4 * PAGE_SIZE`
+    /// or the underlying allocation fails.
     pub fn new(contained: T) -> Self {
+        Self::try_new(contained).expect("allocation too large")
+    }
+
+    /// Creates a new locked box with `contained` in a newly allocated,
+    /// `mlock`-protected region of memory.
+    ///
+    /// Returns `None` if `size_of::<T>() >= usize::MAX - 4 * PAGE_SIZE` or the
+    /// underlying allocation fails.
+    pub fn try_new(contained: T) -> Option<Self> {
         // SAFETY: no references are made to the data contained by the allocated
         // memory until after `contained` as been written. The size of the
         // allocation is checked by `memsec`.
         let memory = unsafe {
-            let memory = memsec::malloc::<T>().expect("allocation too large");
+            let memory = memsec::malloc::<T>()?;
             // It is important to lock the memory before storing the value,
             // otherwise the process could be preempted between the write and
             // the mlock calls, and the memory theoretically could be paged to
@@ -41,7 +51,7 @@ impl<T> LockedBox<T> {
             ptr::write(memory.as_ptr(), contained);
             memory
         };
-        Self(memory)
+        Some(Self(memory))
     }
 
     /// Returns the pointer to the underlying data.