Re: [trans-mem] Add documentation

[Richard Henderson <rth@redhat.com>]

On 05/26/2011 12:19 PM, Torvald Riegel wrote:
> +@subsection State manipulation functions
> +There is no @code{getTransaction} function. Transaction identifiers for
> +nested transactions will be ordered but not necessarily sequential (i.e., for
> +a nested transaction's identifier @code{IN} and its enclosing transaction's
> +identifier @code{IE}, it is guaranteed that @code{IN - IE < 1}).

Err.. surely IN >= IE.

Also, I think you want to use @var not @code here, and maybe @math
for the relation expression.

> +The intention behind @code{_ITM_dropReferences} is not entirely clear. The
> +specification suggests that this function is necessary because of certain
> +orderings of data transfer undos and the releasing of memory regions (i.e.,
> +privatization). However, this ordering is never defined, nor is the ordering of
> +dropping references w.r.t. other events.

I'm pretty sure dropReferences was supposed to be related to cancel+throw,
where we needed to keep modifications to the object thrown from the 
transaction, while rolling back all other changes.

At the time I quit working on this, the TM Language group hadn't made up
it's mind what cancel+throw really meant.  Frankly, it seems a bit 
impossible to me.

> +Registered tables must be writable by the TM runtime, and must be live
> +throughout the life-time of the TM runtime.
> +
> +@strong{TODO} We might want to drop the ``writable'' requirement, and make a
> +copy instead.

The intention was always to drop the registration functions entirely, and
create a new ELF Phdr describing the linker-sorted table.  Much like what
currently happens for PT_GNU_EH_FRAME.

This work kept getting bogged down in how to represent the N different code
generation variants.  We clearly needed at least 2 -- sw and hw transactional
clones -- but there was always a suggestion of more variants for different
tm assumptions/invariants.

> +The ABI should define a memory model and the ordering that is guaranteed for
> +data transfers and commit/undo actions, or at least refer to another memory
> +model that needs to be preserved. Without that, the compiler cannot ensure the
> +memory model specified on the level of the programming language (e.g., by the
> +C++ TM specification).

I thought the TM Language group, and Hans Bohem in particular, has been
working on this.  It post-dates the language spec we had available when
the branch code was written.

Most of the actual texinfo markup looks fine to my untrained eye.


r~