On 05/03/2019 04.06, George Spelvin wrote: > * The comparison function @cmp must return a negative value if @a > * should sort before @b, and a positive value if @a should sort after > * @b. If @a and @b are equivalent, and their original relative > * ordering is to be preserved, @cmp must return 0. > + * > + * (Actually, it is always called with @a being the element which was > + * originally first, so it is not necessary to to distinguish the @a < @b > + * and @a == @b cases; the return value may be a simple boolean. But if > + * you ever *use* this freedom, be sure to update this comment to document > + * that code now depends on preserving this property!) > */
This was and still is used at least by the block layer, and likely others as well. While 3110fc79606fb introduced a bunch of if() return -1 else if () ... stuff, it still ends with a 0/1 result. Before 3110fc79606fb, it was even more obvious that this property was used. So I agree that it is worth documenting this feature, both for users of list_sort, but even more so for future refactorers of it - but you probably want to change the wording somewhat. Grepping around shows that this could probably be used in more places, gaining a cycle or two per cmp callback, e.g. xfs_buf_cmp. But that's of course outside the scope of this series. Rasmus
