Home Comments

Documentation re: stack-allocated servants

greg_hallgreg_hall Member
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

Comments

  • michimichi Member Michi HenningOrganization: Triodia TechnologiesProject: I have a passing interest in Ice :-) ✭✭✭
    Re: Documentation re: stack-allocated servants
    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.
  • dhalbertdhalbert Member
    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_hallgreg_hall Member
    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
  • michimichi Member Michi HenningOrganization: Triodia TechnologiesProject: I have a passing interest in Ice :-) ✭✭✭
    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.
  • bolidecasterbolidecaster Member
    Those XREF markers confused me as well. Thanks for clarifing that.
Sign In or Register to comment.