From 74212ed96e777056020f2fb1360dbeead0247693 Mon Sep 17 00:00:00 2001
From: Christian Schwarz <me@cschwarz.com>
Date: Mon, 14 Aug 2023 15:00:55 +0000
Subject: [PATCH] some doc comments

---
 .../src/tenant/ephemeral_file/buffer_pool.rs  | 22 ++++++++++++++++++-
 .../src/tenant/ephemeral_file/dirty_buffer.rs |  2 ++
 2 files changed, 23 insertions(+), 1 deletion(-)

diff --git a/pageserver/src/tenant/ephemeral_file/buffer_pool.rs b/pageserver/src/tenant/ephemeral_file/buffer_pool.rs
index d22df01f2f..9987654a57 100644
--- a/pageserver/src/tenant/ephemeral_file/buffer_pool.rs
+++ b/pageserver/src/tenant/ephemeral_file/buffer_pool.rs
@@ -1,3 +1,9 @@
+//! Buffer pool for ephemeral file buffers.
+//!
+//! Currently this is a very simple implementation that just uses `malloc`.
+//! But the interface is such that we can switch to a more sophisticated
+//! implementation later, e.g., one that caps that amount of memory used.
+
 use std::ops::{Deref, DerefMut};
 
 use crate::page_cache::PAGE_SZ;
@@ -6,11 +12,25 @@ pub struct BufferPool;
 
 const POOL: BufferPool = BufferPool;
 
-pub fn get() -> &'static BufferPool {
+pub(super) fn get() -> &'static BufferPool {
     &POOL
 }
 
 impl BufferPool {
+    /// Get a [`Handle`] to a buffer in the pool.
+    ///
+    /// The buffer is guaranteed to be zeroed out.
+    ///
+    /// The implementation may block to wait for buffers to become available,
+    /// and a future async version of this method may `.await` internally to
+    /// wait for buffers to become available.
+    ///
+    /// To avoid deadlocks, a thread/task must get all the buffers it needs
+    /// with a single call to `get_buffer`. Without this rule, a deadlock
+    /// can happen. Take for example a buffer pool with 2 buffers X, Y
+    /// and a program with two threads A and B, each requiring 2 buffers.
+    /// If A gets X and B gets Y, then both threads will block forever trying
+    /// to get their second buffer.
     pub fn get_buffer(&self) -> Handle {
         Handle {
             data: vec![0; PAGE_SZ],
diff --git a/pageserver/src/tenant/ephemeral_file/dirty_buffer.rs b/pageserver/src/tenant/ephemeral_file/dirty_buffer.rs
index cc7111a11a..a5ad14f19f 100644
--- a/pageserver/src/tenant/ephemeral_file/dirty_buffer.rs
+++ b/pageserver/src/tenant/ephemeral_file/dirty_buffer.rs
@@ -1,3 +1,5 @@
+//! Newtypes to ensure that dirty buffers are written back to the filesystem before they are dropped.
+
 use std::io::ErrorKind;
 use std::ops::Deref;
 use std::ops::DerefMut;