From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from firstgate.proxmox.com (firstgate.proxmox.com [IPv6:2a01:7e0:0:424::9]) by lore.proxmox.com (Postfix) with ESMTPS id 500B21FF15C for ; Wed, 26 Mar 2025 15:21:37 +0100 (CET) Received: from firstgate.proxmox.com (localhost [127.0.0.1]) by firstgate.proxmox.com (Proxmox) with ESMTP id A5F0939336; Wed, 26 Mar 2025 15:21:14 +0100 (CET) From: Max Carrara To: pve-devel@lists.proxmox.com Date: Wed, 26 Mar 2025 15:20:56 +0100 Message-Id: <20250326142059.261938-6-m.carrara@proxmox.com> X-Mailer: git-send-email 2.39.5 In-Reply-To: <20250326142059.261938-1-m.carrara@proxmox.com> References: <20250326142059.261938-1-m.carrara@proxmox.com> MIME-Version: 1.0 X-SPAM-LEVEL: Spam detection results: 0 AWL 0.074 Adjusted score from AWL reputation of From: address BAYES_00 -1.9 Bayes spam probability is 0 to 1% DMARC_MISSING 0.1 Missing DMARC policy KAM_DMARC_STATUS 0.01 Test Rule for DKIM or SPF Failure with Strict Alignment SPF_HELO_NONE 0.001 SPF: HELO does not publish an SPF Record SPF_PASS -0.001 SPF: sender matches SPF record Subject: [pve-devel] [PATCH v1 pve-storage 5/8] pluginbase: document hooks X-BeenThere: pve-devel@lists.proxmox.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Proxmox VE development discussion List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Reply-To: Proxmox VE development discussion Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Errors-To: pve-devel-bounces@lists.proxmox.com Sender: "pve-devel" Add docstrings for the following methods: - on_add_hook - on_update_hook - on_delete_hook Signed-off-by: Max Carrara --- src/PVE/Storage/PluginBase.pm | 85 ++++++++++++++++++++++++++++++----- 1 file changed, 74 insertions(+), 11 deletions(-) diff --git a/src/PVE/Storage/PluginBase.pm b/src/PVE/Storage/PluginBase.pm index 8a61dc3..b3ce684 100644 --- a/src/PVE/Storage/PluginBase.pm +++ b/src/PVE/Storage/PluginBase.pm @@ -626,29 +626,92 @@ sub find_free_diskname { =head2 HOOKS +The following methods are called whenever a storage associated with the given +plugin is added, updated, or deleted. These methods are useful for: + +=over + +=item * Setting up certain prerequisites when adding the storage (and then +tearing them down again when the storage is deleted) + +=item * Handling sensitive parameters that shouldn't be written directly +to C and ought to be stored elsewhere + +=item * Ensuring that certain conditions in the configuration are being upheld +that cannot be done via the remaining API otherwise + +=back + +and more. + +=cut + +=head3 $plugin->on_add_hook($storeid, \%scfg, %param) + +=head3 $plugin->on_add_hook(...) + +B May be implemented in a storage plugin. + +Called during the addition of a storage, before the new storage configuration +gets written. + +C<%param> contains additional key-value arguments, usually sensitive keys that +have been extracted from C<\%scfg> in order not to write them to the storage +configuration. + +Cs in order to abort the addition if there are (grave) problems. + +C is B when this method is called. + =cut -# called during addition of storage (before the new storage config got written) -# die to abort addition if there are (grave) problems -# NOTE: runs in a storage config *locked* context sub on_add_hook { my ($class, $storeid, $scfg, %param) = @_; return undef; } -# called during storage configuration update (before the updated storage config got written) -# die to abort the update if there are (grave) problems -# NOTE: runs in a storage config *locked* context +=head3 $plugin->on_update_hook($storeid, \%scfg, %param) + +=head3 $plugin->on_update_hook(...) + +B May be implemented in a storage plugin. + +Called during the update of a storage configuration, before the new +configuration gets written. + +C<%param> contains additional key-value arguments, usually sensitive keys that +have been extracted from C<\%scfg> in order not to write them to the storage +configuration. + +Cs in order to abort the config update if there are (grave) problems. + +C is B when this method is called. + +=cut + sub on_update_hook { my ($class, $storeid, $scfg, %param) = @_; return undef; } -# called during deletion of storage (before the new storage config got written) -# and if the activate check on addition fails, to cleanup all storage traces -# which on_add_hook may have created. -# die to abort deletion if there are (very grave) problems -# NOTE: runs in a storage config *locked* context +=head3 $plugin->on_delete_hook($storeid, \%scfg) + +=head3 $plugin->on_delete_hook(...) + +B May be implemented in a storage plugin. + +Called during the deletion of a storage, before the new storage configuration +gets written. Also gets called if the activation check during storage +addition fails in order to clean up all traces which +Con_add_hook($storeid, \%scfg, %param)" >>> +may have created. + +Cs in order to abort the deletion of there are (very grave) problems. + +C is B when this method is called. + +=cut + sub on_delete_hook { my ($class, $storeid, $scfg) = @_; return undef; -- 2.39.5 _______________________________________________ pve-devel mailing list pve-devel@lists.proxmox.com https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel