通用監管者行為。

此行為模組提供了一個監管者，一個監管其他稱為子程序的程序。子程序可以是另一個監管者或一個工作程序。工作程序通常使用 gen_event、gen_server 或 gen_statem 行為之一來實現。使用此模組實現的監管者具有一組標準的介面函數，並包含追蹤和錯誤報告的功能。監管者用於建立一個稱為監管樹的階層式程序結構，這是一種組織容錯應用程式的好方法。有關更多資訊，請參閱 OTP 設計原則中的監管者行為。

監管者期望在回呼模組中指定要監管的子程序定義，並匯出預定義的函數集。

除非另有說明，否則如果指定的監管者不存在或指定了錯誤的參數，則此模組中的所有函數都會失敗。

監管原則

監管者負責啟動、停止和監控其子程序。監管者的基本概念是，它必須透過在必要時重新啟動子程序來保持其子程序存活。

監管者的子程序定義為子程序規格的列表。當監管者啟動時，會根據此列表從左到右依序啟動子程序。當監管者即將終止時，它會先以反向的啟動順序，從右到左終止其子程序。

監管者旗標

監管者的屬性由監管者旗標定義。監管者旗標的類型定義如下

sup_flags() = #{strategy => strategy(),           % optional
                intensity => non_neg_integer(),   % optional
                period => pos_integer(),          % optional
                auto_shutdown => auto_shutdown()} % optional

重新啟動策略

監管者可以使用上述映射中的 strategy 鍵來指定以下其中一種重新啟動策略

• one_for_one - 如果一個子程序終止且要重新啟動，則只會影響該子程序。這是預設的重新啟動策略。

• one_for_all - 如果一個子程序終止且要重新啟動，則會終止所有其他子程序，然後重新啟動所有子程序。

• rest_for_one - 如果一個子程序終止且要重新啟動，則會終止「其餘」的子程序（也就是說，啟動順序中已終止的子程序之後的子程序）。然後重新啟動已終止的子程序以及其後的所有子程序。

• simple_one_for_one - 簡化的 one_for_one 監管者，其中所有子程序都是相同程序類型的動態新增實例，也就是說，執行相同的程式碼。

  函數 delete_child/2 和 restart_child/2 對於 simple_one_for_one 監管者無效，如果指定的監管者使用此重新啟動策略，則會傳回 {error,simple_one_for_one}。

  函數 terminate_child/2 可以透過指定子程序的 pid/0 作為第二個參數，用於 simple_one_for_one 監管者下的子程序。如果改為使用子程序規格識別碼，則 terminate_child/2 會傳回 {error,simple_one_for_one}。

  由於 simple_one_for_one 監管者可以有很多子程序，它會非同步關閉所有子程序。這表示子程序會平行進行清理，因此停止它們的順序未定義。

重新啟動強度和週期

為了防止監管者陷入子程序終止和重新啟動的無限迴圈，會使用上述映射中具有鍵 intensity 和 period 的兩個整數值定義最大重新啟動強度。假設 intensity 的值為 MaxR，period 的值為 MaxT，那麼，如果在 MaxT 秒內發生超過 MaxR 次的重新啟動，則監管者會終止所有子程序，然後自行終止。在這種情況下，監管者本身的終止原因將為 shutdown。intensity 預設為 1，而 period 預設為 5。

自動關閉

可以使用上述映射中的 auto_shutdown 鍵，將監管者設定為在 重要子程序 以退出原因 shutdown 終止時自動關閉。

• never - 停用自動關閉。這是預設設定。

  當 auto_shutdown 設定為 never 時，將 significant 旗標設定為 true 的子程序規格被視為無效，且會被拒絕。

• any_significant - 當任何重要子程序終止時，監管者會自行關閉，也就是說，當 transient 重要子程序正常終止時，或者當 temporary 重要子程序正常或異常終止時。

• all_significant - 當所有重要子程序都終止時，監管者會自行關閉，也就是說，當最後一個活動的重要子程序終止時。與 any_significant 相同的規則適用。

有關更多資訊，請參閱 OTP 設計原則中監管者行為的自動關閉一節。

警告

自動關閉功能在 OTP 24.0 中出現，但使用此功能的應用程式也可以使用較舊的 OTP 版本編譯和執行。

但是，當使用早於自動關閉功能出現的 OTP 版本編譯此類應用程式時，會洩漏程序，因為它們所依賴的自動關閉不會發生。

如果實作者預期他們的應用程式可能會使用較舊的 OTP 版本編譯，則應採取適當的預防措施。

子程序規格

子程序規格的類型定義如下

child_spec() = #{id => child_id(),             % mandatory
                 start => mfargs(),            % mandatory
                 restart => restart(),         % optional
                 significant => significant(), % optional
                 shutdown => shutdown(),       % optional
                 type => worker(),             % optional
                 modules => modules()}         % optional

為了向後相容性，保留了舊的元組格式，請參閱 child_spec/0，但優先使用映射。

• id 用於讓監管者在內部識別子程序規格。

  id 鍵是必要的。

  請注意，這個識別碼有時被稱為「名稱」。盡可能使用「識別碼」或「id」等術語，但為了保持向後相容性，仍然可以找到某些「名稱」的出現，例如在錯誤訊息中。

• start 定義用於啟動子程序的函數呼叫。它必須是一個模組-函數-參數元組 {M,F,A}，用作 apply(M,F,A)。

  啟動函數必須建立並連結到子程序，而且必須傳回 {ok,Child} 或 {ok,Child,Info}，其中 Child 是子程序的 pid，而 Info 是監管者忽略的任何詞彙。

  如果由於某些原因無法啟動子程序，則啟動函數也可以傳回 ignore，在這種情況下，監管者會保留子程序規格（除非它是暫時子程序），但會忽略不存在的子程序。

  如果發生錯誤，該函數也可以傳回錯誤元組 {error,Error}。

  請注意，不同行為模組的 start_link 函數符合上述要求。

  start 鍵是必要的。

• restart 定義何時必須重新啟動已終止的子程序。permanent 子程序總是會重新啟動。temporary 子程序永遠不會重新啟動（即使監管者的重新啟動策略為 rest_for_one 或 one_for_all 且同級的終止導致暫時程序被終止）。只有當 transient 子程序異常終止時，才會重新啟動（也就是說，以 normal、shutdown 或 {shutdown,Term} 以外的退出原因終止）。

  restart 鍵是可選的。如果未指定，則預設為 permanent。

• significant 定義子程序是否被視為監管者的自動自行關閉的重要程序。

  當 重新啟動類型為 permanent 時，將此選項設定為 true 無效。此外，當 auto_shutdown 監管者旗標設定為 never 時，在監管者中啟動將此選項設定為 true 的子程序也被視為無效。

  significant 鍵是可選的。如果未指定，則預設為 false。

• shutdown 定義了子程序必須如何終止。brutal_kill 表示子程序會使用 exit(Child,kill) 無條件終止。整數的逾時值表示 supervisor 會呼叫 exit(Child,shutdown) 來告知子程序終止，然後等待子程序回傳原因為 shutdown 的結束訊號。如果在指定的毫秒數內沒有收到結束訊號，子程序會使用 exit(Child,kill) 無條件終止。

  如果子程序是另一個 supervisor，則必須將關閉時間設定為 infinity，以便給子樹足夠的時間關閉。

  警告

  對於類型為 supervisor 的子程序，將關閉時間設定為除了 infinity 以外的任何值，可能會導致競爭條件，其中相關的子程序會取消連結其自身的子程序，但在被終止之前未能終止它們。

  如果子程序是 worker，也可以將其設定為 infinity。

  警告

  當子程序是 worker 時，請謹慎將關閉時間設定為 infinity。因為在這種情況下，監督樹的終止取決於子程序，它必須以安全的方式實作，並且其清理程序必須始終返回。

  請注意，所有使用標準 OTP 行為模組實作的子程序都會自動遵守關閉協定。

  shutdown 鍵是可選的。如果未指定，則如果子程序的類型為 worker，則預設為 5000；如果子程序的類型為 supervisor，則預設為 infinity。

• type 指定子程序是 supervisor 還是 worker。

  type 鍵是可選的。如果未指定，則預設為 worker。

• modules 在程式碼替換期間由釋出處理常式使用，以確定哪些程序正在使用特定模組。根據經驗法則，如果子程序是 supervisor、gen_server 或 gen_statem，則此值為一個包含一個元素 [Module] 的列表，其中 Module 是回呼模組。如果子程序是具有動態回呼模組集的事件管理器 (gen_event)，則必須使用值 dynamic。有關釋出處理的更多資訊，請參閱 OTP 設計原則中的 釋出處理。

  modules 鍵是可選的。如果未指定，則預設為 [M]，其中 M 來自子程序的啟動 {M,F,A}。

• 在內部，supervisor 還會追蹤子程序的 pid Child，如果不存在 pid 則追蹤 undefined。

另請參閱

gen_event、gen_statem、gen_server、sys