The first words that came into my head when I learned about the ExtendKit toolkit for FrameMaker were garbage collection. Writing FDK programs is (mostly) a lot of fun but figuring out how to correctly allocate and deallocate memory is tricky and error prone. JavaScript purports to free one from those complexities.
So I was a bit surprised to see that the Scripting Guide documentation for GetText() and methods such as GetProps(), Save() and others contain notes that are similar to that shown below.
So apparently memory management is still something script writers must contend with.
If you call GetText(), do you absolutely need to call the DeallocateTextItems() method to free the memory used when you are done? If you are getting a small number of text items, you are very likely safe if you forget or don't bother to deallocate. But if you call GetText() on a large quantity of text (possibly in many documents), failure to deallocate can be a problem. This is also the case if a script might be called many, many times before FrameMaker is restarted.
The FDK has the F_ApiBailOut() command which purports to direct a plug-in to stop running and give back its memory when it completes a command. I was never confident this did anything on Windows and there appears to be no analog in ExtendScript. Only Adobe knows how the scripts are implemented at that level. All one can be sure of is that when the user exits FrameMaker, any memory used by scripts is freed.
So, I tried to be a good citizen and deallocate my text items:
var tItems = mainflow.GetText(Constants.FTI_CharPropsChange | Constants.FTI_TextObjId |
Constants.FTI_String);
PrintTextItems(tItems);
app.DeallocateTextItems(tItems);//WRONG
But I ran into a problem. I could not find a single example of the appropriate use of DeallocateTextItems()or the other deallocate methods anywhere. and my attempt to use this function produced the following error:
So I was a bit surprised to see that the Scripting Guide documentation for GetText() and methods such as GetProps(), Save() and others contain notes that are similar to that shown below.
"Note: The returned TextItems structure references memory that is allocated by the method. Use the DeallocateTextItems() method to free this memory when you are done with using it."
So apparently memory management is still something script writers must contend with.
If you call GetText(), do you absolutely need to call the DeallocateTextItems() method to free the memory used when you are done? If you are getting a small number of text items, you are very likely safe if you forget or don't bother to deallocate. But if you call GetText() on a large quantity of text (possibly in many documents), failure to deallocate can be a problem. This is also the case if a script might be called many, many times before FrameMaker is restarted.
The FDK has the F_ApiBailOut() command which purports to direct a plug-in to stop running and give back its memory when it completes a command. I was never confident this did anything on Windows and there appears to be no analog in ExtendScript. Only Adobe knows how the scripts are implemented at that level. All one can be sure of is that when the user exits FrameMaker, any memory used by scripts is freed.
So, I tried to be a good citizen and deallocate my text items:
var tItems = mainflow.GetText(Constants.FTI_CharPropsChange | Constants.FTI_TextObjId |
Constants.FTI_String);
PrintTextItems(tItems);
app.DeallocateTextItems(tItems);//WRONG
But I ran into a problem. I could not find a single example of the appropriate use of DeallocateTextItems()or the other deallocate methods anywhere. and my attempt to use this function produced the following error:
What is going on? Is this a documentation error or my error? I have yet to figure this one out.
Debra,
ReplyDeleteThe inclusion DeallocateTextItems() was a documentation error. This has been fixed in the latest version of the Scripting Guide.
http://help.adobe.com/en_US/framemaker/scripting/index.html
One way to double check this is to look at the ESTK data browser. This is a tree view of the available functions. With FrameMaker 10 running and the target application, select 'app' from the list. You will not find DeallocateTextItems().
By the way there are several undocumented functions in that list...
Thanks again Ian. I did not realize I had an old version of the docs. I did look at the tree view and did not find deallocate functions but as the message was in the docs so many times I felt unsure as to whether or not I was missing something.
ReplyDeleteSo good news, deallocation does not concern ESTK scripters.