spmallette commented on code in PR #3471: URL: https://github.com/apache/tinkerpop/pull/3471#discussion_r3454321224
########## docs/src/reference/the-traversal.asciidoc: ########## @@ -213,8 +214,25 @@ occurs. `Transaction.READ_WRITE_BEHAVIOR` contains pre-defined `Consumer` functi method. It has two options: * `AUTO` - automatic transactions where the transaction is started implicitly to the read or write operation -* `MANUAL` - manual transactions where it is up to the user to explicitly open a transaction, throwing an exception -if the transaction is not open +* `MANUAL` - manual transactions where it is up to the user to explicitly begin a transaction with `begin()`, +throwing an exception if the transaction is not open + +The `begin()` method is idempotent with respect to an open transaction: calling it when a transaction is already open +does not start a new transaction and does not throw - it returns a `TraversalSource` bound to the transaction that is +already open. This behavior is what allows `begin()` to coexist with `AUTO`. Under `AUTO`, a read or write implicitly +opens a transaction, so an explicit `begin()` issued afterward would otherwise be operating on an already-open +transaction; because `begin()` is idempotent, that call is safe rather than an error. Likewise, `close()` is +idempotent - closing a transaction that is not open is a no-op. + +How `begin()` behaves once a transaction has been closed depends on the transaction model, and the two reference +models differ here intentionally: + +* *Embedded* transactions are typically thread-bound and reusable. After a `commit()` or `rollback()`, the same Review Comment: "typically" - using this word because providers might have different semantics in embedded mode? if so, i think that should be spelled out clearly. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
