From nobody Mon Dec 15 09:42:40 2025 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of lists.libvirt.org designates 8.43.85.245 as permitted sender) client-ip=8.43.85.245; envelope-from=devel-bounces@lists.libvirt.org; helo=lists.libvirt.org; Authentication-Results: mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of lists.libvirt.org designates 8.43.85.245 as permitted sender) smtp.mailfrom=devel-bounces@lists.libvirt.org; dmarc=fail(p=none dis=none) header.from=redhat.com Return-Path: Received: from lists.libvirt.org (lists.libvirt.org [8.43.85.245]) by mx.zohomail.com with SMTPS id 1741800552880157.168973519578; Wed, 12 Mar 2025 10:29:12 -0700 (PDT) Received: by lists.libvirt.org (Postfix, from userid 996) id 2B28E2102; Wed, 12 Mar 2025 13:29:12 -0400 (EDT) Received: from lists.libvirt.org (localhost [IPv6:::1]) by lists.libvirt.org (Postfix) with ESMTP id 4AF591F57; Wed, 12 Mar 2025 13:26:39 -0400 (EDT) Received: by lists.libvirt.org (Postfix, from userid 996) id 62E581D99; Wed, 12 Mar 2025 13:26:35 -0400 (EDT) Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by lists.libvirt.org (Postfix) with ESMTPS id EEA621F5B for ; Wed, 12 Mar 2025 13:25:56 -0400 (EDT) Received: from mx-prod-mc-06.mail-002.prod.us-west-2.aws.redhat.com (ec2-35-165-154-97.us-west-2.compute.amazonaws.com [35.165.154.97]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-327-q2UPp40lNgiHZx5DcGVkfg-1; Wed, 12 Mar 2025 13:25:55 -0400 Received: from mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.111]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 67BBA18EFA61 for ; Wed, 12 Mar 2025 17:18:29 +0000 (UTC) Received: from toolbx.redhat.com (unknown [10.42.28.57]) by mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id BBB9518001D4; Wed, 12 Mar 2025 17:18:27 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on lists.libvirt.org X-Spam-Level: X-Spam-Status: No, score=-0.8 required=5.0 tests=DKIM_INVALID,DKIM_SIGNED, HEADER_FROM_DIFFERENT_DOMAINS,MAILING_LIST_MULTI,RCVD_IN_DNSWL_NONE, RCVD_IN_MSPIKE_H5,RCVD_IN_MSPIKE_WL,RCVD_IN_VALIDITY_RPBL_BLOCKED, RCVD_IN_VALIDITY_SAFE_BLOCKED,SPF_HELO_NONE autolearn=unavailable autolearn_force=no version=3.4.4 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741800356; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=+GrpoPXzEcQG9XiJglQK67l1gqU24PMtDq2w21rSuWs=; b=FOYPUM+qgQyuRyoHjJbfgZ4YEzOdo1FvXM04F937jsZDTdWRzpdkNxoqTFTkRwKSaj59cE 9IRAFMWY9tYQU7A0O5elKlCDM+7380t2Qj1hySHES+VkKnrwWYa57jhx7jqLMvxms1shyQ FGmbQZJBovdg48IVAmDyNdZ2MK3dntM= X-MC-Unique: q2UPp40lNgiHZx5DcGVkfg-1 X-Mimecast-MFC-AGG-ID: q2UPp40lNgiHZx5DcGVkfg_1741800354 From: =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= To: devel@lists.libvirt.org Cc: =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= Subject: [PATCH v2 15/22] src: clarify semantics of the various virStateNNN methods Date: Wed, 12 Mar 2025 17:17:55 +0000 Message-ID: <20250312171802.1854985-16-berrange@redhat.com> In-Reply-To: <20250312171802.1854985-1-berrange@redhat.com> References: <20250312171802.1854985-1-berrange@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.111 X-Mimecast-Spam-Score: 0 X-Mimecast-MFC-PROC-ID: OUApyADOf3N9bJ59RFA06uhDset_DejrlhKwDiY0u3k_1741800354 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable Message-ID-Hash: HCSVWWBML3ZRPDFTABRIJQDQGIXJQUFW X-Message-ID-Hash: HCSVWWBML3ZRPDFTABRIJQDQGIXJQUFW X-MailFrom: berrange@redhat.com X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; emergency; loop; banned-address; member-moderation; header-match-config-1; header-match-config-2; header-match-config-3; header-match-devel.lists.libvirt.org-0; nonmember-moderation; administrivia; implicit-dest; max-recipients; max-size; news-moderation; no-subject; suspicious-header X-Mailman-Version: 3.2.2 Precedence: list List-Id: Development discussions about the libvirt library & tools Archived-At: List-Archive: List-Help: List-Post: List-Subscribe: List-Unsubscribe: X-ZohoMail-DKIM: fail (Header signature does not verify) X-ZM-MESSAGEID: 1741800555132019000 Content-Type: text/plain; charset="utf-8" It is not documented what the various virStateNNN methods are each responsible for doing and the names give little guidance either. Provide some useful documentation comments to explain the intended usage of each. Signed-off-by: Daniel P. Berrang=C3=A9 Reviewed-by: Peter Krempa --- src/libvirt.c | 44 +++++++++++++++++++++++++++++++++++++++----- 1 file changed, 39 insertions(+), 5 deletions(-) diff --git a/src/libvirt.c b/src/libvirt.c index 1d37696d6f..581fc6deea 100644 --- a/src/libvirt.c +++ b/src/libvirt.c @@ -688,7 +688,13 @@ virStateInitialize(bool privileged, /** * virStateShutdownPrepare: * - * Run each virtualization driver's shutdown prepare method. + * Tell each driver to prepare for shutdown of the daemon. This should + * trigger any actions required to stop processing background work. + * + * This method is called directly from the main event loop thread, so + * the event loop will not execute while this method is running. After + * this method returns, the event loop will continue running until + * the virStateShutdownWait method completes. * * Returns 0 if all succeed, -1 upon any failure. */ @@ -709,7 +715,12 @@ virStateShutdownPrepare(void) /** * virStateShutdownWait: * - * Run each virtualization driver's shutdown wait method. + * Tell each driver to finalize any work required to enable + * graceful shutdown of the daemon. This method is invoked + * from a background thread, and when it completes, the event + * loop will terminate. As such drivers can register callbacks + * that will prevent the event loop terminating until actions + * initiated by virStateShutdownPrepare are complete. * * Returns 0 if all succeed, -1 upon any failure. */ @@ -730,7 +741,12 @@ virStateShutdownWait(void) /** * virStateCleanup: * - * Run each virtualization driver's cleanup method. + * Tell each driver to release all resources it holds in + * order to fully shutdown the daemon. When this is called + * the event loop will no longer be running. Thus any + * cleanup that depends on execution of the event loop + * must have been triggered by the virStateShutdownPrepare + * method. * * Returns 0 if all succeed, -1 upon any failure. */ @@ -752,7 +768,8 @@ virStateCleanup(void) /** * virStateReload: * - * Run each virtualization driver's reload method. + * Tell each driver to reload their global configuration + * file(s). * * Returns 0 if all succeed, -1 upon any failure. */ @@ -774,7 +791,24 @@ virStateReload(void) /** * virStateStop: * - * Run each virtualization driver's "stop" method. + * Tell each driver to prepare for system/session stop. + * + * In an unprivileged daemon, this indicates that the + * current user's primary login session is about to + * be terminated. + * + * In a privileged daemon, this indicates that the host + * OS is about to shutdown. + * + * This is a signal that the driver should stop and/or + * preserve any resources affected by the system/session + * stop. + * + * On host OS stop there is a very short wait for the + * stop action to complete. For any prolonged tasks + * the driver must acquire inhibitor locks, or send + * a request to systemd to extend the shutdown wait + * timeout. * * Returns 0 if successful, -1 on failure */ --=20 2.48.1