What is the reason for C-RW-VALUE?

[tbu-]

Generic reader/writer functions take R: Read and W: Write by value (C-RW-VALUE).

https://rust-lang-nursery.github.io/api-guidelines/interoperability.html#c-rw-value
https://github.com/rust-lang-nursery/api-guidelines/blob/05a1d5e5568606442c770919d167513dbbf78024/src/interoperability.md#generic-readerwriter-functions-take-r-read-and-w-write-by-value-c-rw-value

[tbu-]

I see a reason against it, for every such function down the call stack, you'll add one reference to the reader/writer object. This is inefficient if the compiler doesn't notice that and can rewrite function signatures (which is only the case if it knows all call sites).

E.g. just having two levels of such functions results in &mut &mut &mut File, because each of the functions, including the one calling read or write needs to add another reference layer, it cannot pass the object by-value if it needs to call another method on that object. File is just a 32-bit integer on Linux, hiding it behind three references makes it slower.

[dtolnay]

Performance was not a motivation for the guideline. It is chiefly about clarity and simplicity.

Compare the amount of noise in these signatures:

use std::io::Write;

fn write_by_value<W: Write>(_w: W) {}

fn write_by_mut_ref<W: ?Sized + Write>(_w: &mut W) {}

Counting everything but the function names, the second one is 60% more characters and all of that is noise. It's not even more usable -- the noise amounts to making the function usable with strictly fewer types.

Compare also the call site:

let mut buffer = [0u8; 256];

write_by_value(&mut buffer[..]);

// oh my god
write_by_mut_ref(&mut &mut buffer[..]);

The mut ref one is hard to use because Write implementations are built around the expectation that the implementor is passed by value.

By value is also more suitable for writer adapters:

write_by_value(Adapter::new(&mut underlying));

// :(
write_by_mut_ref(&mut Adapter::new(&mut underlying));

[tbu-]

Hm. Can we point out the disadvantages in this approach in the docs?

[KodrAus]

Performance caveats are a bit of a cross-cutting concern for API design that probably impact a number of guidelines, not just this one.

I'll go ahead and close this one, but but I think there's room for another resource on performance-sympathetic tactics.