[PATCH] docs: Use 'live' or 'lively' to describe the device events

Han Han posted 1 patch 2 weeks, 6 days ago
Patches applied successfully (tree, apply log)
git fetch https://github.com/patchew-project/libvirt tags/patchew/20211118021206.1643080-1-hhan@redhat.com
include/libvirt/libvirt-domain.h | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)

[PATCH] docs: Use 'live' or 'lively' to describe the device events

Posted by Han Han 2 weeks, 6 days ago
The event of device added or removed only happens at live attachment or
detachment. Make the comments more explicit.

Signed-off-by: Han Han <hhan@redhat.com>
---
 include/libvirt/libvirt-domain.h | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/include/libvirt/libvirt-domain.h b/include/libvirt/libvirt-domain.h
index 2f017c5b68..25ee06d0d6 100644
--- a/include/libvirt/libvirt-domain.h
+++ b/include/libvirt/libvirt-domain.h
@@ -4148,7 +4148,7 @@ typedef void (*virConnectDomainEventPMSuspendDiskCallback)(virConnectPtr conn,
  * @devAlias: device alias
  * @opaque: application specified data
  *
- * This callback occurs when a device is removed from the domain.
+ * This callback occurs when a device is lively removed from the domain.
  *
  * The callback signature to use when registering for an event of type
  * VIR_DOMAIN_EVENT_ID_DEVICE_REMOVED with virConnectDomainEventRegisterAny()
@@ -4165,7 +4165,7 @@ typedef void (*virConnectDomainEventDeviceRemovedCallback)(virConnectPtr conn,
  * @devAlias: device alias
  * @opaque: application specified data
  *
- * This callback occurs when a device is added to the domain.
+ * This callback occurs when a device is lively added to the domain.
  *
  * The callback signature to use when registering for an event of type
  * VIR_DOMAIN_EVENT_ID_DEVICE_ADDED with virConnectDomainEventRegisterAny()
@@ -4183,7 +4183,7 @@ typedef void (*virConnectDomainEventDeviceAddedCallback)(virConnectPtr conn,
  * @devAlias: device alias
  * @opaque: application specified data
  *
- * This callback occurs when it's certain that removal of a device failed.
+ * This callback occurs when it's certain that live removal of a device failed.
  *
  * The callback signature to use when registering for an event of type
  * VIR_DOMAIN_EVENT_ID_DEVICE_REMOVAL_FAILED with
-- 
2.33.1

Re: [PATCH] docs: Use 'live' or 'lively' to describe the device events

Posted by Daniel P. Berrangé 2 weeks, 5 days ago
On Thu, Nov 18, 2021 at 10:12:06AM +0800, Han Han wrote:
> The event of device added or removed only happens at live attachment or
> detachment. Make the comments more explicit.
> 
> Signed-off-by: Han Han <hhan@redhat.com>
> ---
>  include/libvirt/libvirt-domain.h | 6 +++---
>  1 file changed, 3 insertions(+), 3 deletions(-)
> 
> diff --git a/include/libvirt/libvirt-domain.h b/include/libvirt/libvirt-domain.h
> index 2f017c5b68..25ee06d0d6 100644
> --- a/include/libvirt/libvirt-domain.h
> +++ b/include/libvirt/libvirt-domain.h
> @@ -4148,7 +4148,7 @@ typedef void (*virConnectDomainEventPMSuspendDiskCallback)(virConnectPtr conn,
>   * @devAlias: device alias
>   * @opaque: application specified data
>   *
> - * This callback occurs when a device is removed from the domain.
> + * This callback occurs when a device is lively removed from the domain.

Good idea to improve it, but "lively" feels a bit akward, how
about we phase it as:

   "...a device is removed from a running domain"


>   *
>   * The callback signature to use when registering for an event of type
>   * VIR_DOMAIN_EVENT_ID_DEVICE_REMOVED with virConnectDomainEventRegisterAny()
> @@ -4165,7 +4165,7 @@ typedef void (*virConnectDomainEventDeviceRemovedCallback)(virConnectPtr conn,
>   * @devAlias: device alias
>   * @opaque: application specified data
>   *
> - * This callback occurs when a device is added to the domain.
> + * This callback occurs when a device is lively added to the domain.
>   *
>   * The callback signature to use when registering for an event of type
>   * VIR_DOMAIN_EVENT_ID_DEVICE_ADDED with virConnectDomainEventRegisterAny()
> @@ -4183,7 +4183,7 @@ typedef void (*virConnectDomainEventDeviceAddedCallback)(virConnectPtr conn,
>   * @devAlias: device alias
>   * @opaque: application specified data
>   *
> - * This callback occurs when it's certain that removal of a device failed.
> + * This callback occurs when it's certain that live removal of a device failed.
>   *
>   * The callback signature to use when registering for an event of type
>   * VIR_DOMAIN_EVENT_ID_DEVICE_REMOVAL_FAILED with
> -- 
> 2.33.1
> 

Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|

Re: [PATCH] docs: Use 'live' or 'lively' to describe the device events

Posted by Han Han 2 weeks, 5 days ago
On Thu, Nov 18, 2021 at 6:35 PM Daniel P. Berrangé <berrange@redhat.com>
wrote:

> On Thu, Nov 18, 2021 at 10:12:06AM +0800, Han Han wrote:
> > The event of device added or removed only happens at live attachment or
> > detachment. Make the comments more explicit.
> >
> > Signed-off-by: Han Han <hhan@redhat.com>
> > ---
> >  include/libvirt/libvirt-domain.h | 6 +++---
> >  1 file changed, 3 insertions(+), 3 deletions(-)
> >
> > diff --git a/include/libvirt/libvirt-domain.h
> b/include/libvirt/libvirt-domain.h
> > index 2f017c5b68..25ee06d0d6 100644
> > --- a/include/libvirt/libvirt-domain.h
> > +++ b/include/libvirt/libvirt-domain.h
> > @@ -4148,7 +4148,7 @@ typedef void
> (*virConnectDomainEventPMSuspendDiskCallback)(virConnectPtr conn,
> >   * @devAlias: device alias
> >   * @opaque: application specified data
> >   *
> > - * This callback occurs when a device is removed from the domain.
> > + * This callback occurs when a device is lively removed from the domain.
>
> Good idea to improve it, but "lively" feels a bit akward, how
> about we phase it as:
>
Here I aimed to use 'lively' to describe the action of detaching.
For the "running domain", I think it is not so accurate:
A device removal could also be done by `virsh detach-device VM XML
--config` with the running VM. However, that will not cause the
'device-removed' event.

>
>    "...a device is removed from a running domain"
>
>
> >   *
> >   * The callback signature to use when registering for an event of type
> >   * VIR_DOMAIN_EVENT_ID_DEVICE_REMOVED with
> virConnectDomainEventRegisterAny()
> > @@ -4165,7 +4165,7 @@ typedef void
> (*virConnectDomainEventDeviceRemovedCallback)(virConnectPtr conn,
> >   * @devAlias: device alias
> >   * @opaque: application specified data
> >   *
> > - * This callback occurs when a device is added to the domain.
> > + * This callback occurs when a device is lively added to the domain.
> >   *
> >   * The callback signature to use when registering for an event of type
> >   * VIR_DOMAIN_EVENT_ID_DEVICE_ADDED with
> virConnectDomainEventRegisterAny()
> > @@ -4183,7 +4183,7 @@ typedef void
> (*virConnectDomainEventDeviceAddedCallback)(virConnectPtr conn,
> >   * @devAlias: device alias
> >   * @opaque: application specified data
> >   *
> > - * This callback occurs when it's certain that removal of a device
> failed.
> > + * This callback occurs when it's certain that live removal of a device
> failed.
> >   *
> >   * The callback signature to use when registering for an event of type
> >   * VIR_DOMAIN_EVENT_ID_DEVICE_REMOVAL_FAILED with
> > --
> > 2.33.1
> >
>
> Regards,
> Daniel
> --
> |: https://berrange.com      -o-
> https://www.flickr.com/photos/dberrange :|
> |: https://libvirt.org         -o-
> https://fstop138.berrange.com :|
> |: https://entangle-photo.org    -o-
> https://www.instagram.com/dberrange :|
>
>