Documentation re: stack-allocated servants

[greg_hall]

Version 1.0.2 of the Ice documentation states in "10.7.1 Instantiating a Servant":

"Instantiating a servant means to allocate an instance, either on the stack or on the heap. Most commonly, servants are instantiated on the heap because we want the servant instance to endure beyond the duration of the current stack frame:"

This is rather misleading in practical terms in the light of the section, "Stack-Allocated Class Instances" in "6.14.5 Smart Pointers for Classes" which states:

"...allocating class instances on the stack is pragmatically useless because all the Ice APIs expect parameters that are smart pointers..."

and goes on to demonstrate the dangers of using stack-allocated classes with smart pointers.

Wouldn't it be better to state in 10.7.1 that servants *must* be allocated on the heap (as with the later CORBA specs) or provide a cross-ref to the appropriate part of 6.14.5? Or can a sensible example of stack-allocated servants be provided in the documentation?

Cheers,

Greg

BTW, a few of the cross-references seem to be broken in 10.7.2-3

[michi]

Originally posted by greg_hall
Version 1.0.2 of the Ice documentation states in "10.7.1 Instantiating a Servant":

"Instantiating a servant means to allocate an instance, either on the stack or on the heap. Most commonly, servants are instantiated on the heap because we want the servant instance to endure beyond the duration of the current stack frame:"

This is rather misleading in practical terms in the light of the section, "Stack-Allocated Class Instances" in "6.14.5 Smart Pointers for Classes" which states:

"...allocating class instances on the stack is pragmatically useless because all the Ice APIs expect parameters that are smart pointers..."

and goes on to demonstrate the dangers of using stack-allocated classes with smart pointers.

Wouldn't it be better to state in 10.7.1 that servants *must* be allocated on the heap (as with the later CORBA specs) or provide a cross-ref to the appropriate part of 6.14.5? Or can a sensible example of stack-allocated servants be provided in the documentation?

Cheers,

Greg

BTW, a few of the cross-references seem to be broken in 10.7.2-3

Hi Greg! (Long time no talk )

You caught me out there.

Yes, you are right -- allocating servants on the stack is something that's fraught with danger and best not done at all. I'll fix this for the next version of the doc, thanks!

I'll have a look at the broken XREF. Do you have a page number?

Thanks,

Michi.

[dhalbert]

I'll have a look at the broken XREF. Do you have a page number?

Michi,

You can find them all systematically by doing a search for "XREF" in the 1.0.2 .pdf file (use Acrobat Reader Edit->Find, its binoculars icon, etc.). Quite a few show up.

Regards,
Dan

[greg_hall]

I'll have a look at the broken XREF. Do you have a page number?

I found them on pages 245 and 247-49.

HTH,

Greg

[michi]

Originally posted by dhalbert
Michi,

You can find them all systematically by doing a search for "XREF" in the 1.0.2 .pdf file (use Acrobat Reader Edit->Find, its binoculars icon, etc.). Quite a few show up.

Regards,
Dan

Ah, OK, misunderstanding. These cross references are in the text deliberately. They point at things that we intended to refer to at that point, but the text they refer to hasn't been written yet. So, these XREF markers will be progressively resolved as we add more material.

Cheers,

Michi.

[bolidecaster]

Those XREF markers confused me as well. Thanks for clarifing that.