initial draft

source/sdk/kotlin/realm-database/write-transactions.txt

@@ -52,7 +52,7 @@ condition when reading values from the realm within a
 transaction.
 
 When you are done with your transaction, Realm either
-**commits** it or **cancels** it:
+commits it or cancels it:
 
 - When Realm **commits** a transaction, Realm writes
   all changes to disk. For synced realms, the SDK queues the change
@@ -61,6 +61,43 @@ When you are done with your transaction, Realm either
   the transaction causes an error, all changes are discarded
   (or "rolled back").
 
+Managed vs. Unmanaged Objects
+-----------------------------
+
+Realm objects written to a realm are either managed or unmanaged by Realm.
+
+Managed Objects
+~~~~~~~~~~~~~~~
+
+**Managed objects** are live Realm objects that update based on changes 
+to underlying data in Realm. Managed objects can only come from an open 
+realm and receive updates as long as that realm remains open. 
+
+Managed objects can use Realm APIs, be queried, create relationships with 
+other objects, and be observed for changes. You create managed objects 
+with 
+`Realm.copyToRealm() <{+kotlin-local-prefix+}io.realm.kotlin.dynamic/-dynamic-mutable-realm/copy-to-realm.html>`__. 
+See :ref:`Create Realm Objects <kotlin-create-a-new-object>` for more 
+information.
+
+.. note:: 
+
+   You can :ref:`create managed asymmetric objects <kotlin-create-asymmetric-object>`. 
+   But because asymmetric objects are write-only, it isn't possible to 
+   access the managed data after it has been written.
+
+Unmanaged Objects
+~~~~~~~~~~~~~~~~~
+
+**Unmanaged objects** are instances of Realm objects that are not live. They 
+behave like normal Kotlin objects, but they are not persisted in a realm.
+You can get an unmanaged object by manually constructing a Realm object 
+yourself or by calling 
+`Realm.copyFromRealm() <{+kotlin-local-prefix+}io.realm.kotlin.ext/copy-from-realm.html>`__. 
+
+You can create a managed copy of an unmanaged object with 
+`Realm.copyToRealm() <{+kotlin-local-prefix+}io.realm.kotlin.dynamic/-dynamic-mutable-realm/copy-to-realm.html>`__. 
+
 .. _kotlin-open-a-transaction:
 
 Run a Transaction
@@ -86,3 +123,4 @@ the transaction immediately after the callback.
 
    .. literalinclude:: /examples/generated/kotlin/CRUDTest.snippet.run-a-transaction.kt
       :language: kotlin
+