From de5868e099a3133f964c2f7c1d2a26ced571b9da Mon Sep 17 00:00:00 2001
From: Jacek Laskowski <jacek@japila.pl>
Date: Thu, 28 Dec 2023 18:20:01 +0100
Subject: [PATCH] BroadcastFactory and the only implementation
 TorrentBroadcastFactory

---
 docs/broadcast-variables/BroadcastFactory.md  | 42 +++++++++---
 .../TorrentBroadcastFactory.md                | 67 +++++++++++--------
 2 files changed, 72 insertions(+), 37 deletions(-)

diff --git a/docs/broadcast-variables/BroadcastFactory.md b/docs/broadcast-variables/BroadcastFactory.md
index 3089096769..497705d9d4 100644
--- a/docs/broadcast-variables/BroadcastFactory.md
+++ b/docs/broadcast-variables/BroadcastFactory.md
@@ -1,10 +1,10 @@
 # BroadcastFactory
 
-`BroadcastFactory` is an [abstraction](#contract) of [broadcast variable factories](#implementations) that [BroadcastManager](BroadcastManager.md) uses to [create](#newBroadcast) or [delete](#unbroadcast) broadcast variables.
+`BroadcastFactory` is an [abstraction](#contract) of [broadcast variable factories](#implementations) that [BroadcastManager](BroadcastManager.md) uses to [create](#newBroadcast) or [delete](#unbroadcast) (_unbroadcast_) broadcast variables.
 
 ## Contract
 
-### <span id="initialize"> Initializing
+### Initializing { #initialize }
 
 ```scala
 initialize(
@@ -12,34 +12,53 @@ initialize(
   conf: SparkConf): Unit
 ```
 
+??? warning "Procedure"
+    `initialize` is a procedure (returns `Unit`) so _what happens inside stays inside_ (paraphrasing the [former advertising slogan of Las Vegas, Nevada](https://idioms.thefreedictionary.com/what+happens+in+Vegas+stays+in+Vegas)).
+
+See:
+
+* [TorrentBroadcastFactory](TorrentBroadcastFactory.md#initialize)
+
 Used when:
 
 * `BroadcastManager` is requested to [initialize](BroadcastManager.md#initialize)
 
-### <span id="newBroadcast"> Creating Broadcast Variable
+### Creating Broadcast Variable { #newBroadcast }
 
 ```scala
-newBroadcast(
+newBroadcast[T: ClassTag](
   value: T,
   isLocal: Boolean,
-  id: Long): Broadcast[T]
+  id: Long,
+  serializedOnly: Boolean = false): Broadcast[T]
 ```
 
+See:
+
+* [TorrentBroadcastFactory](TorrentBroadcastFactory.md#newBroadcast)
+
 Used when:
 
 * `BroadcastManager` is requested for a [new broadcast variable](BroadcastManager.md#newBroadcast)
 
-### <span id="stop"> Stopping
+### Stopping { #stop }
 
 ```scala
 stop(): Unit
 ```
 
+??? warning "Procedure"
+    `stop` is a procedure (returns `Unit`) so _what happens inside stays inside_ (paraphrasing the [former advertising slogan of Las Vegas, Nevada](https://idioms.thefreedictionary.com/what+happens+in+Vegas+stays+in+Vegas)).
+
+See:
+
+* [TorrentBroadcastFactory](TorrentBroadcastFactory.md#stop)
+
 Used when:
 
 * `BroadcastManager` is requested to [stop](BroadcastManager.md#stop)
 
-### <span id="unbroadcast"> Deleting Broadcast Variable
+### Deleting Broadcast Variable { #unbroadcast }
 
 ```scala
 unbroadcast(
@@ -48,9 +67,16 @@ unbroadcast(
   blocking: Boolean): Unit
 ```
 
+??? warning "Procedure"
+    `unbroadcast` is a procedure (returns `Unit`) so _what happens inside stays inside_ (paraphrasing the [former advertising slogan of Las Vegas, Nevada](https://idioms.thefreedictionary.com/what+happens+in+Vegas+stays+in+Vegas)).
+
+See:
+
+* [TorrentBroadcastFactory](TorrentBroadcastFactory.md#unbroadcast)
+
 Used when:
 
-* `BroadcastManager` is requested to [delete a broadcast variable](BroadcastManager.md#unbroadcast)
+* `BroadcastManager` is requested to [delete a broadcast variable](BroadcastManager.md#unbroadcast) (_unbroadcast_)
 
 ## Implementations
 
diff --git a/docs/broadcast-variables/TorrentBroadcastFactory.md b/docs/broadcast-variables/TorrentBroadcastFactory.md
index 7c44c9c2dc..433252d0d4 100644
--- a/docs/broadcast-variables/TorrentBroadcastFactory.md
+++ b/docs/broadcast-variables/TorrentBroadcastFactory.md
@@ -11,50 +11,59 @@
 
 `TorrentBroadcastFactory` is created for [BroadcastManager](BroadcastManager.md#broadcastFactory).
 
-## <span id="newBroadcast"> Creating Broadcast Variable
+## Creating Broadcast Variable { #newBroadcast }
 
-```scala
-newBroadcast(
-  value_ : T,
-  isLocal: Boolean,
-  id: Long): Broadcast[T]
-```
+??? note "BroadcastFactory"
+
+    ```scala
+    newBroadcast[T: ClassTag](
+      value_ : T,
+      isLocal: Boolean,
+      id: Long,
+      serializedOnly: Boolean = false): Broadcast[T]
+    ```
+
+    `newBroadcast` is part of the [BroadcastFactory](BroadcastFactory.md#newBroadcast) abstraction.
 
 `newBroadcast` creates a new [TorrentBroadcast](TorrentBroadcast.md) with the given `value_` and `id` (and ignoring `isLocal`).
 
-`newBroadcast` is part of the [BroadcastFactory](BroadcastFactory.md#newBroadcast) abstraction.
+## Deleting Broadcast Variable { #unbroadcast }
+
+??? note "BroadcastFactory"
 
-## <span id="unbroadcast"> Deleting Broadcast Variable
+    ```scala
+    unbroadcast(
+      id: Long,
+      removeFromDriver: Boolean,
+      blocking: Boolean): Unit
+    ```
 
-```scala
-unbroadcast(
-  id: Long,
-  removeFromDriver: Boolean,
-  blocking: Boolean): Unit
-```
+    `unbroadcast` is part of the [BroadcastFactory](BroadcastFactory.md#unbroadcast) abstraction.
 
 `unbroadcast` [removes all persisted state associated with the broadcast variable](TorrentBroadcast.md#unpersist) (identified by `id`).
 
-`unbroadcast` is part of the [BroadcastFactory](BroadcastFactory.md#unbroadcast) abstraction.
+## Initializing { #initialize }
 
-## <span id="initialize"> Initializing
+??? note "BroadcastFactory"
 
-```scala
-initialize(
-  isDriver: Boolean,
-  conf: SparkConf): Unit
-```
+    ```scala
+    initialize(
+      isDriver: Boolean,
+      conf: SparkConf): Unit
+    ```
+
+    `initialize` is part of the [BroadcastFactory](BroadcastFactory.md#initialize) abstraction.
 
 `initialize` does nothing (_noop_).
 
-`initialize` is part of the [BroadcastFactory](BroadcastFactory.md#initialize) abstraction.
+## Stopping { #stop }
 
-## <span id="stop"> Stopping
+??? note "BroadcastFactory"
 
-```scala
-stop(): Unit
-```
+    ```scala
+    stop(): Unit
+    ```
 
-`stop` does nothing (_noop_).
+    `stop` is part of the [BroadcastFactory](BroadcastFactory.md#stop) abstraction.
 
-`stop` is part of the [BroadcastFactory](BroadcastFactory.md#stop) abstraction.
+`stop` does nothing (_noop_).