Looking for input on naming the pmem_mem* functions

[Andy Rudoff]

Our libpmem provides low-level helper functions for using persistent memory.  Those functions include ways to flush stores to persistence and optimized ways to copy to persistence.  I'm trying to decide the best naming for these entry points:

pmem_memcpy()
pmem_memmove()
pmem_memset()

They are described in the man page at http://pmem.io/nvml/libpmem/libpmem.3.html

These functions are optimized for copying *to* pmem.  Using them to copy from pmem to DRAM will work, but will actually be slower than just using the libc functions since all the flushing to persistence will be wasted on DRAM destinations.  I try to make that clear by naming the arguments things like "src" and "pmemdest" and by having text in the man page that says they are for the case when the destination is pmem.

But many people (me included) just see the function name and assume what it does so I'm wondering if the names should be something like:

pmem_memcpy_to_pmem()
pmem_memmove_to_pmem()
pmem_memset_to_pmem()

That seems potentially clearer, but I seems a bit ugly.

Anyone care to give input on the naming of these functions?

Thanks,

-andy

[Zach Brown]

I'm not a huge fan of the 'to_pmem' suffix as it doesn't really describe
what the function does. It describes what the argument is.

My initial gut reaction is to:

1) rename to pmem_mem{cpy,move,set}_persist()
- hints at the call to pmem_persist() in each copy call
- seems consistent with _nodrain() naming

2) change the manual describing "the result has" to specifically mention
the destination parameter name.. maybe "len bytes at pmemdest have".

3) Replace the final WARNING sentence with a paragraph of clear
statements. I don't think there's much risk of people arbitrarily using
these in code that has nothing to do with pmem. But they might think
that they need to use it for the source range. So just call that out.
"These functions are only needed if the destination range is pmem. They
do not treat the source range any differently than the usual copying
functions. memcpy(), memmove(), or memset() should be used if only the
source is pmem to avoid slowing down writes to the destination with
unnecessary flushing."

Or something to that effect :).

- z

[Jeff Moyer]

Andy Rudoff <an...@rudoff.com> writes:

> Anyone care to give input on the naming of these functions?

I say leave them as is. Documentation is there for a reason. Do you
warn about invocations that don't make sense when debugging is enabled?
If not, you could add that.

Cheers,
Jeff

[Alasdair G Kergon]

[resent]

I'm with Jeff on this.

The code still works fine if people use the pmem_ prefix when they don't need
it and the "only needed in one direction" rule is very easy to grasp.

Alasdair