How to understand shared passing of a MTensor in LibraryLink?

Question

According to the documentation, there are four different type of memory managing when passing a MTensor with LibraryLink: Automatic, "Constant", "Manual" and "Shared".

The Automatic and "Manual" is easy to understand, since in both of them, the MTensor get copied and passed into the library function. The difference between them is wether the tensor will be automatically clean or not. The "Constant" and "Shared" will pass a reference of the MTensor into the library function, and "Constant" promises the library function to not change the MTensor.

I find "Shared" is difficult for me to understand. Does the "Shared" passing means that variable in Mathematica and my library function point to the same data buffer in the memory? And if I change on one side, the changes will be transparent on the other side ?

Consider this example from the document:

loadFun = 
  LibraryFunctionLoad["demo_shared", 
   "loadArray", {{Real, _, "Shared"}}, Integer];
unloadFun = 
  LibraryFunctionLoad["demo_shared", "unloadArray", {}, Integer];
getFunVector = 
  LibraryFunctionLoad["demo_shared", "getElementVector", {Integer}, 
   Real];

If we load the library function with an array

array = Range[1., 20];
loadFun[ array]

and change the array on the Mathematica side

array[[1]] = 2.;
getFunVector[ 1]
(* 1. *)

why the data on the library side not changed?

Also, in the documentation, it says after call unload, which disowns the MTensor, array cannot be used anymore,

unloadFun[ ]
(* 0 *)

getFunVector[1]
(* 1. *)

array[[1]]
(* 2. *)

but why I can still use it? What does disown do?

Answer 1

I'm not sure whether I will get everything right here, but to my knowledge the key-point is indeed MTensor_disown. When you call loadFun you basically move the write-priviliges for the array to your library functions. This means, changing values inside the library will be transparent on the Mathematica side. Let's load the library functions:

loadFun = LibraryFunctionLoad["demo_shared", "loadArray", {{Real, 1, "Shared"}}, Integer];
unloadFun = LibraryFunctionLoad["demo_shared", "unloadArray", {}, Integer];
setFunVector = LibraryFunctionLoad["demo_shared", "setElementVector",
    {Integer, Real}, Integer];
getArray = LibraryFunctionLoad["demo_shared", "getArray", {}, {Real, 1}];

Look at this example which loads an array, sets up a dynamic watcher and changes a value from the library side. Note that we watch both, the array on Mathematica side and the MTensor in the library!

array = Range[1., 20];
loadFun[array];   
Dynamic[Refresh[Column@{array, getArray[]}, UpdateInterval -> .5]]

If you now evaluate a setFunVector[4, -1] you see that both lists are updated because they represent the same tensor.

However, what you have to keep in mind is that as long as you have not disowned the tensor in the library, you have not right to change the values from Mathematica side. If you do it anyway, then I guess Mathematica copies the current tensor and lets you modify this instead. Once you have done this, you have two tensors and changing the value from inside the library will only change your original one:

array[[1]] = 0
(*
  {0,2.,3.,-1.,5.,6.,7.,8.,9.,10.,11.,12.,13.,14.,15.,16.,17.,18.,19.,20.}
  {1.,2.,3.,-1.,5.,6.,7.,8.,9.,10.,11.,12.,13.,14.,15.,16.,17.,18.,19.,20.}
*)

And now see that only the library tensor is changed

setFunVector[4, 10]
(*
  {0,2.,3.,-1.,5.,6.,7.,8.,9.,10.,11.,12.,13.,14.,15.,16.,17.,18.,19.,20.}
  {1.,2.,3.,10.,5.,6.,7.,8.,9.,10.,11.,12.,13.,14.,15.,16.,17.,18.,19.,20.}
*)

The conclusion is that you cannot have parallel access from both sides. If you want to make a change from within Mathematica you have to disown the tensor in the library, change it inside Mathematica and re-load it. This is my understanding of the situation.

Edit

I forgot one important thing which was pointed out by rasher in the comments: Every time you pass a tensor to the library in shared mode, Mathematica makes an entry in a shared tensor table. Therefore, if you pass it several times without disowning it, you will end up having several entries in this table and one call to MTensor_disown is not enough. You have to call it as often as you have passed the tensor to the library. For this the function MTensor_disownAll is convenient.

Furthermore, while we are at the topic of passing shared tensors from Mathematica to a library function: There is additionally the possibility to return shared tensors. You can read about this in the official documentation.