search

digitalocean / go-libvirt

Package libvirt provides a pure Go interface for interacting with Libvirt. Apache 2.0 Licensed.
Apache License 2.0
928 stars 127 forks source link

Q: What is the meaning of `NeedResults`? #197

Open CarstenLeue opened 1 year ago

CarstenLeue commented 1 year ago

Some methods, e.g. NetworkGetDhcpLeases have a NeedResults parameter of type int32. What is the meaning of this parameter, is this a flag indicating that we need a result list, so I should pass in 1 or is this the number (max?) of results to be expected?

sihensel commented 7 months ago

@CarstenLeue we stumbled over the same question. NeedResults specifies whether the method should return the actual result list or not and is used as a boolean flag.

This behavior is implemented in libvirt here: https://github.com/libvirt/libvirt/blob/40ebade891a0d2c08e82dac126822d5ee57f4281/src/rpc/gendispatch.pl#L994 If need_results is set (i.e. contains any non-zero value) the result list will be returned, otherwise the return value is NULL.

Furthermore, most methods that fetch data from libvirt take a pointer to a data buffer as input. If the pointer is valid (i.e. not NULL), need_results will be set to 1: https://github.com/libvirt/libvirt/blob/40ebade891a0d2c08e82dac126822d5ee57f4281/src/rpc/gendispatch.pl#L1729 Sidenote: !! converts any non-zero value to 1 while making sure that 0 remains 0.

This behavior is also documented in the docs, e.g. for virConnectListAllDomains: https://libvirt.org/html/libvirt-libvirt-domain.html#virConnectListAllDomains Note the description of the domains parameter:

Pointer to a variable to store the array containing domain objects or NULL if the list is not required (just returns number of guests).

Go-libvirt emulates this behavior and returns an empty list if NeedResults is set to 0, while returning the actual objects if it is set to 1. This could have been mentioned in the docs here somewhere though.