docs: shareData() is read-once on POSIX but repeatable on Windows #89

Problem

man/shareData.Rd says:

The shared object can be read once: getData unlinks the memory map as soon as it has read the data, so calling getData again with the same map_name fails.

That is true on POSIX (Linux, macOS) but not on Windows. The test suite already knows this:

• inst/tinytest/test-share.R:22-26: on Windows, a second getData() returns the data again; on POSIX it errors.
• src/share.c: releaseReadMapping() ignores unlink_names on Windows, so the named mapping stays alive while the owner's handle is open.

The page also does not explain what happens if the sharing session is killed:

• POSIX: the object can stay in /dev/shm on Linux.
• Windows: the mapping disappears when the last handle closes.

This is a follow-up to #60, which rewrote the deep-copy explanation. The cross-platform lifetime is still wrong.

What to change

Rewrite man/shareData.Rd with:

• A short description: share one object between two R sessions on the same machine.
• map_name: a leading / is added if missing; use a simple name; do not pass a path or a Windows Global/Local prefix.
• A platform table or \describe{} with POSIX vs Windows lifetime.
• A note that getData() on POSIX unlinks before unserialize(), so a corrupt object cannot be read twice.
• A note that sharing is same-machine, same-user; it is not a network protocol.
• A note about /dev/shm size limits on Linux and in containers.
• Keep the existing deep-copy explanation and the link to shareData() without deep copy? #43.

\details{
  \strong{This is a copy, not a live pointer.}
  \code{shareData()} serializes \code{data} to a raw vector and copies it into
  shared memory. \code{getData()} copies the raw vector back and unserializes
  it. The object is copied twice, so large objects take time and memory.

  \strong{Lifetime and platform differences.}
  \describe{
    \item{POSIX (Linux, macOS, and other Unix-like systems)}{
      \code{getData()} unlinks the shared memory object after reading it, so a
      second call with the same \code{map_name} fails. The object stays alive
      while the pointer returned by \code{shareData()} exists. If the sharing
      session is killed, the object can remain in \code{/dev/shm} on Linux
      until it is removed or the machine reboots.
    }
    \item{Windows}{
      \code{getData()} closes its handles but does not delete the mapping, so a
      second call succeeds while the sharing session is alive.
      \code{clearData()} removes the mapping when the last handle is closed.
      If the sharing session is killed, Windows closes its handles and the
      mapping disappears.
    }
  }

  \strong{Scope.}
  Sharing works only on one machine and for the same user. It does not send
  data over a network. Use the same R version and the same version of
  \pkg{kit} when possible. External pointers and connections do not survive;
  environments are copied, not shared.

  \strong{Memory limits.}
  The operating system limits shared memory. On Linux, \code{/dev/shm} is
  often smaller than RAM, especially in containers. A large object can
  therefore fail even when the machine has enough memory.
}

Acceptance

• The page no longer says "read once" for all platforms.
• The Windows repeat-read behavior is documented and matches test-share.R.
• The POSIX unlink and /dev/shm persistence are documented.
• tools::checkRd("man/shareData.Rd") passes.

Related

• docs: clarify shareData deep-copy cost vs #43 zero-copy #60 (closed): earlier shareData docs rewrite.
• shareData() without deep copy? #43 (open): zero-copy request. This issue is only about documenting the current contract.