Re: [RFC PATCH v1 1/8] qapi: golang: Generate qapi's enum types in Go

["Daniel P. Berrangé" <berrange@redhat.com>]

On Sat, Apr 02, 2022 at 12:40:57AM +0200, Victor Toso wrote:
> This patch handles QAPI enum types and generates its equivalent in Go.
> 
> The highlights of this implementation are:
> 
> 1. For each QAPI enum, we will define an int32 type in Go to be the
>    assigned type of this specific enum

I think there's a potential case to be made for considering
representation of enums as strings in Golang, as it more
gracefully degrades.

Consider the 'SHUTDOWN' event in QEMU, which has a 'reason' field.

This implementation has

type ShutdownCause int32

const (
        ShutdownCauseNone               ShutdownCause = iota
        ShutdownCauseHostError                        // An error prevents further use of guest
        ShutdownCauseHostQmpQuit                      // Reaction to the QMP command 'quit'
        ShutdownCauseHostQmpSystemReset               // Reaction to the QMP command 'system_reset'
        ShutdownCauseHostSignal                       // Reaction to a signal, such as SIGINT
        ShutdownCauseHostUi                           // Reaction to a UI event, like window close
        ShutdownCauseGuestShutdown                    // Guest shutdown/suspend request, via ACPI or other hardware-specific means
        ShutdownCauseGuestReset                       // Guest reset request, and command line turns that into a shutdown
        ShutdownCauseGuestPanic                       // Guest panicked, and command line turns that into a shutdown
        ShutdownCauseSubsystemReset                   // Partial guest reset that does not trigger QMP events and ignores --no-reboot. This is useful for sanitizing hypercalls on s390 that are used during kexec/kdump/boot
)


and


type ShutdownEvent struct {
        Guest  bool          `json:"guest"`  // If true, the shutdown was triggered by a guest request (such as a guest-initiated ACPI shutdown request or other hardware-specific action) rather than a host request (such as sending qemu a SIGINT). (since 2.10)
        Reason ShutdownCause `json:"reason"` // The @ShutdownCause which resulted in the SHUTDOWN. (since 4.0)
}

Consider that the application is compiled against the QAPI generated
API from QEMU 7.0. The application is believed to run happily against
7.1, because app doesn't need any of the functionality added in 7.1
QAPI.  But consider that QEMU 7.1 had introduced a new shutdown reason
value.

The application may want to know that the guest has shutdown, but does
NOT care about the  reason for the shutdown.

Since the ShutdownReason is implemented as an int though, the unmarshalling
for the reason field is going to fail.

If the enums were just represented as strings, then we can gracefully
accept any new enum value that arrives in future. The application can
thus also still log the shutdown reason string, even though it was not
a value explicitly known to the generated API.

> 
> 2. While in the Go codebase we can use the generated enum values, the
>    specification requires that, on the wire, the enumeration type's
>    value to be represented by its string name.
> 
>    For this reason, each Go type that represent's a QAPI enum will be
>    implementing the Marshaler[0] and Unmarshaler[1] interfaces to
>    seamless handle QMP's string to Go int32 value and vice-versa.
> 
> 3. Naming: CamelCase will be used in any identifier that we want to
>    export [2], which is everything in this patch.

With 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 :|