<div dir="ltr"><div>--- </div>Here's the updated patch. Thanks, Bill and Kristian, for your reviews. Feel free to let me know if anything else needs correcting with this one. <div> src/wayland-util.h | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/src/wayland-util.h b/src/wayland-util.h index de2e464..bed8d2a 100644 --- a/src/wayland-util.h +++ b/src/wayland-util.h @@ -111,6 +111,33 @@ int wl_list_length(const struct wl_list *list); int wl_list_empty(const struct wl_list *list); void wl_list_insert_list(struct wl_list *list, struct wl_list *other); +/** + * Retrieves a pointer to the containing struct of a given member item. + * + * This macro allows conversion from a pointer to a item to its containing + * struct. This is useful if you have a contained item like a wl_list, + * wl_listener, or wl_signal, provided via a callback or other means and would + * like to retrieve the struct that contains it. + * + * To demonstrate, given a wl_list contained by a wl_resource in a member + * called link, the wl_resource can be retrieved as follows: + * + * \code + * struct wl_list *some_link = ...; + * struct wl_resource *resource = NULL; + * + * resource = wl_container_of(some_link, resource, link); + * \endcode + * + * \param ptr A valid pointer to the contained item. + * + * \param sample A pointer to the type of content that the list item stores. + * Sample does not need be a valid pointer; a null pointer will suffice. + * + * \param member The named location of ptr within the sample type. + * + * \return The container for the specified pointer. + */ #ifdef __GNUC__ #define wl_container_of(ptr, sample, member) \ (__typeof__(sample))((char *)(ptr) - \ </div></div>