Thomas Linder Puls: category

2016-03-04T09:46:46Z

Thomas Linder Puls: categorized

2008-01-19T21:47:58Z

categorized

← Older revision		Revision as of 23:47, 19 January 2008
Line 168:		Line 168:

	[[Category:Tutorials]]		[[Category:Tutorials]]
			[[Category:Memory Handling]]

Kari Rastas at 09:17, 3 October 2007

2007-10-03T09:17:23Z

← Older revision		Revision as of 11:17, 3 October 2007
Line 1:		Line 1:
	The Component Object Model (COM) implies usage of COM memory. When we use an external COM component or create our own COM component, we should handle parameters correctly.		The [[wikipedia:Component_object_model\|Component Object Model]] (COM) implies usage of COM memory. When we use an external COM component or create our own COM component, we should handle parameters correctly.

	The IDE generates necessary memory conversions, allocations and releasing on creating of COM package using component's type library. So normally, you do not have to consider the memory handling. However, sometimes some code is written manually, and then the rules must be known.		The IDE generates necessary memory conversions, allocations and releasing on creating of COM package using component's type library. So normally, you do not have to consider the memory handling. However, sometimes some code is written manually, and then the rules must be known.
Line 21:		Line 21:
	==Call a COM Predicate. Handle Returned Memory==		==Call a COM Predicate. Handle Returned Memory==

	When we use an external COM component, we can call a predicate, which returns COM memory to us. Usually we want to use the returned information for some time; hence we should copy the returned memory and free the COM memory then. Once the data is copied to Prolog memory it is controlled by the garbage collector.		When we use an external COM component, we can call a predicate, which returns COM memory to us. Usually we want to use the returned information for some time; hence we should copy the returned memory and free the COM memory then. Once the data is copied to Prolog memory it is controlled by the garbage collector.

	In the example below, the returned parameter has string type.		In the example below, the returned parameter has string type.

Thomas Linder Puls: Move from WEB

2007-08-26T21:25:34Z

Move from WEB

New page

The Component Object Model (COM) implies usage of COM memory. When we use an external COM component or create our own COM component, we should handle parameters correctly.

The IDE generates necessary memory conversions, allocations and releasing on creating of COM package using component's type library. So normally, you do not have to consider the memory handling. However, sometimes some code is written manually, and then the rules must be known.

The possible situations are:

*Call a COM predicate, which returns a parameter in COM memory;

*Call a COM predicate with input parameter;

*Call a COM predicate with input mutable parameter;

*Implement a COM predicate, which gives us a parameter in COM memory;

*Implement a COM predicate, which returns a parameter in COM memory;

*Implement a COM Predicate. In/Out Parameter;

Please notice that integral parameters do not need special memory handling, but strings and structure domains require such memory handling.

==Call a COM Predicate. Handle Returned Memory==

When we use an external COM component, we can call a predicate, which returns COM memory to us. Usually we want to use the returned information for some time; hence we should copy the returned memory and free the COM memory then. Once the data is copied to Prolog memory it is controlled by the garbage collector.

In the example below, the returned parameter has string type.

<vip>clauses
p() = Parameter:-
HResult = someComPredicate(ComParameter),
HResult = s_ok,
!,
Parameter= string::createCopy(ComParameter),
comMemory::taskMemFree(ComParameter).
p() = "".</vip>

==Call a COM Predicate. Fill Input Parameter==

When we use an external COM component, we can call a predicate, which requires our information. We can use any memory for such input parameters. If we use COM memory, then we should free it after the predicate invocation.

In the example below the parameter has myDom type.

<vip>domains
myDom = myDom(integer X, string S).
clauses
q(myDom(X, S)) :-
HResult = someComPredicate(myDom(X, S)),
check(HResult).</vip>

The IDE uses COM memory for input parameters when generating COM code. The IDE also generates the code to release the COM memory.

==Call a COM Predicate. Fill Mutable Parameter==

When we use an external COM component, we can call a predicate, which requires our information and which changes it. We should use COM memory for such parameters. After the call we should free the result COM memory.

In the example below, the parameter has myDom type.

<vip>domains
myDom = myDom(integer X, string S).
clauses
q(myDom(X, S)) = myDom(NewX, NewS):-
ComParameterPtr= comMemory::taskMemAlloc(sizeofdomain(myDom)),
ComS= comMemory::allocString(S),
memory::copy(ComParameterPtr,
uncheckedConvert(pointer,myDom(X, ComS)),
sizeofdomain(myDom)),
ComParameter= uncheckedConvert(myDom, ComParameterPtr)
HResult = someComPredicate(ComParameter),
ComParameter= myDom(NewX, NewComS),
NewS= string::createCopy(NewComS),
comMemory::taskMemFree(NewComS),
comMemory::taskMemFree(ComParameter),
check(HResult).</vip>

Please notice that inner fields can be changed, so it is necessary to find new values and release them.

==Implement a COM Predicate. Handle Input Memory==

When we create our own COM component or when we implement a callback predicate, we can receive a parameter in COM memory.

It is important to notice that this memory should '''not''' be released.

But if we are going to use the information for some time, then we should copy the memory.

In the example below, the parameter has bstr type.

<vip>clauses
someComPredicate(ComParameter) = s_ok :-
trap(somePredicate(basicString::toString(ComParameter)),
TraceId, processTraceId(TraceId)),
!.
someComPredicate(_) = e_fail.

clauses
somePredicate(Parameter) :-
%some implementation here</vip>

Please also notice that Prolog predicates should be trapped, as the COM system cannot process Prolog fail or Prolog exception.

==Implement a COM Predicate. Return Memory==

When we create our own COM component or when we implement a callback predicate, we can be asked about a parameter. Such a parameter must be allocated in COM memory.

So, we should allocate COM memory and fill it with proper values.

In the example below the parameter has myDom type.

<vip>domains
myDom = myDom(integer X, string S).
clauses
someComPredicate(ComParameter) = s_ok :-
trap(
(
myDom(X, S) = somePredicate(),
ComParameterPtr = comMemory::taskMemAlloc(sizeofdomain(myDom)),
ComS= comMemory::allocString(S),
memory::copy(ComParameterPtr,
uncheckedConvert(pointer,myDom(X, ComS)),
sizeofdomain(myDom)),
ComParameter= uncheckedConvert(myDom, ComParameterPtr)
),
TraceId, processTraceId(TraceId)),
!.
someComPredicate(uncheckedConvert(myDom, null)) = e_fail.

clauses
somePredicate() = Parameter :-
%some implementation here</vip>

You can notice that inner parameters of structure domains should be handled as well.

Please also notice that Prolog predicates should be trapped, as COM system cannot process Prolog fail or Prolog exception.

==Implement a COM Predicate. In/Out Parameter==

When we create our own COM component or when we implement a callback predicate, we can receive a memory, which can be changed (i.e. [in, out]).

Then we should allocate COM memory, fill it with proper values, and release the replaced COM memory.

In the example below the parameter has myDom type.

<vip>domains
myDom = myDom(integer X, string S).
clauses
someComPredicate(ComParameter) = s_ok :-
trap(
(
myDom(X, ComS)= ComParameter
S = string::createCopy(ComS),
myDom(NewX, NewS) = somePredicate(myDom(X, S)),
ComParameterPtr= uncheckedConvert(pointer, ComParameter),
comMemory::taskMemFree(ComS),
NewComS = comMemory::allocString(NewS),
memory::copy(ComParameterPtr,
uncheckedConvert(pointer,myDom(NewX, NewComS)),
sizeofdomain(myDom))
),
TraceId, processTraceId(TraceId)),
!.
someComPredicate(_) = e_fail.

clauses
somePredicate(Parameter) = NewParameter :-
%some implementation here</vip>

Please notice the replaced parameter is released after invocation of the Prolog predicate. Hence, an exception in an implementation of somePredicate will not crash the mutable input parameter.

==References==

[[Category:Tutorials]]

← Older revision		Revision as of 11:46, 4 March 2016
Line 167:		Line 167:
	==References==		==References==

	~~[[Category:Tutorials]]~~
	[[Category:Memory Handling]]		[[Category:Memory Handling]]

COM Memory Handling in Visual Prolog - Revision history

Thomas Linder Puls: category

Thomas Linder Puls: categorized

Kari Rastas at 09:17, 3 October 2007

Thomas Linder Puls: Move from WEB