Javadoc-like for Ada

Javadoc-like for Ada

[Alex R. Mosteo]

Hi,

I'm insterested in some doc generation tool ala javadoc; i.e. that not 
only creates a listing like gnathtml but also capable of extracting 
explanations from properly formatted comments in the specification.

I've heard good things about doxygen and I'm going to review it to see 
if it's suitable for Ada.

Any other options I should consider?

Thanks in advance,

A. Mosteo.

Re: Javadoc-like for Ada

[stephane richard]

Hi Alex,

You might want to look at Ada Browse which you can find here
http://home.tiscalinet.ch/t_wolf/tw/ada95/adabrowse/

You might also want to look at AdaDoc which you can find here.
http://sourceforge.net/projects/adadoc/

Hope this helps

Stephane Richard
"Ada World" webmaster
http://www.adaworld.com


"Alex R. Mosteo" <devnull@mailinator.com> wrote in message 
news:41651D37.4030805@mailinator.com...
> Hi,
>
> I'm insterested in some doc generation tool ala javadoc; i.e. that not 
> only creates a listing like gnathtml but also capable of extracting 
> explanations from properly formatted comments in the specification.
>
> I've heard good things about doxygen and I'm going to review it to see if 
> it's suitable for Ada.
>
> Any other options I should consider?
>
> Thanks in advance,
>
> A. Mosteo. 

Re: Javadoc-like for Ada

[Marc A. Criley]

"stephane richard" <stephane.richard@verizon.net> wrote:
> Hi Alex,
>
> You might want to look at Ada Browse which you can find here
> http://home.tiscalinet.ch/t_wolf/tw/ada95/adabrowse/

I want to second the AdaBrowse suggestion.  It's highly configurable,
accurate, does nice pages, and the author Thomas Wolfe has been very
receptive to suggested improvements in operation and adding new features.

Since adopting it, the formatting for all our package spec entity comments
is tailored for extraction by AdaBrowse (which means--hardly tailored at
all, just put them on the correct side-above or below-the construct).

Marc A. Criley
McKae Technologies
www.mckae.com

Re: Javadoc-like for Ada

[Alex R. Mosteo]

Marc A. Criley wrote:
> "stephane richard" <stephane.richard@verizon.net> wrote:
> 
>>Hi Alex,
>>
>>You might want to look at Ada Browse which you can find here
>>http://home.tiscalinet.ch/t_wolf/tw/ada95/adabrowse/
> 
> 
> I want to second the AdaBrowse suggestion.  It's highly configurable,
> accurate, does nice pages, and the author Thomas Wolfe has been very
> receptive to suggested improvements in operation and adding new features.
> 
> Since adopting it, the formatting for all our package spec entity comments
> is tailored for extraction by AdaBrowse (which means--hardly tailored at
> all, just put them on the correct side-above or below-the construct).

Thanks for your suggestions. After summarial review, doxygen doesn't 
support Ada and AdaBrowse seems what I was looking for in any case.

Kind regards,

A. Mosteo.

Problem with -gnatt (was Re: Javadoc-like for Ada)

[Alex R. Mosteo]

Alex R. Mosteo wrote:
> Marc A. Criley wrote:
> 
>> "stephane richard" <stephane.richard@verizon.net> wrote:
>>
>>> Hi Alex,
>>>
>>> You might want to look at Ada Browse which you can find here
>>> http://home.tiscalinet.ch/t_wolf/tw/ada95/adabrowse/
>>
>>
>>
>> I want to second the AdaBrowse suggestion.  It's highly configurable,
>> accurate, does nice pages, and the author Thomas Wolfe has been very
>> receptive to suggested improvements in operation and adding new features.
>>
>> Since adopting it, the formatting for all our package spec entity 
>> comments
>> is tailored for extraction by AdaBrowse (which means--hardly tailored at
>> all, just put them on the correct side-above or below-the construct).
> 
> 
> Thanks for your suggestions. After summarial review, doxygen doesn't 
> support Ada and AdaBrowse seems what I was looking for in any case.

I'm trying now AdaBrowse with a fairly big project of mine and:

When I add the -gnatt switch to get the tree, gnat bails out with a 
"gnat bug detected". Compiling normally it goes ok...

Pretty bad luck.

Re: Problem with -gnatt (was Re: Javadoc-like for Ada)

[Marc A. Criley]

"Alex R. Mosteo" <devnull@mailinator.com> wrote:
>
> I'm trying now AdaBrowse with a fairly big project of mine and:
>
> When I add the -gnatt switch to get the tree, gnat bails out with a
> "gnat bug detected". Compiling normally it goes ok...

Because AdaBrowse uses ASIS, it inherits being very picky about the version
of the GNAT compiler that is being used.

If you're already aware of that aspect, please disregard the following and
just let Thomas Wolfe know about your problem.  He's been very good in the
past about working to overcome problems.

Otherwise, make sure you closely read the "Download" and "Supported
Compilers" section of http://home.tiscalinet.ch/t_wolf/tw/ada95/adabrowse/,
since that goes over the compiler version issue.  Note in particular that
AdaBrowse "will not work with the FSF GNAT in gcc 3.x because there is no
ASIS implementation for that compiler."

Marc

Re: Problem with -gnatt (was Re: Javadoc-like for Ada)

[Björn Persson]

Marc A. Criley wrote:

> Note in particular that
> AdaBrowse "will not work with the FSF GNAT in gcc 3.x because there is no
> ASIS implementation for that compiler."

The version of Asis for Gnat and the included Adabrowse at 
http://gnat-asis.sourceforge.net/ appear to work with GCC 3.4.0. At 
least it processes AdaCL for me without errors.

-- 
Björn Persson                              PGP key A88682FD
                    omb jor ers @sv ge.
                    r o.b n.p son eri nu

Re: Problem with -gnatt (was Re: Javadoc-like for Ada)

[Alex R. Mosteo]

Marc A. Criley wrote:
> "Alex R. Mosteo" <devnull@mailinator.com> wrote:
> 
>>I'm trying now AdaBrowse with a fairly big project of mine and:
>>
>>When I add the -gnatt switch to get the tree, gnat bails out with a
>>"gnat bug detected". Compiling normally it goes ok...
> 
> 
> Because AdaBrowse uses ASIS, it inherits being very picky about the version
> of the GNAT compiler that is being used.
> 
> If you're already aware of that aspect, please disregard the following and
> just let Thomas Wolfe know about your problem.  He's been very good in the
> past about working to overcome problems.
> 
> Otherwise, make sure you closely read the "Download" and "Supported
> Compilers" section of http://home.tiscalinet.ch/t_wolf/tw/ada95/adabrowse/,
> since that goes over the compiler version issue.  Note in particular that
> AdaBrowse "will not work with the FSF GNAT in gcc 3.x because there is no
> ASIS implementation for that compiler."

I'm using gnat 3.15p for linux with its ASIS. If I didn't read wrongly, 
that's a safe combination (not needing any changes furthermore).

Re: Problem with -gnatt

[Ludovic Brenta]

"Alex R. Mosteo" writes:
> I'm trying now AdaBrowse with a fairly big project of mine and:
>
> When I add the -gnatt switch to get the tree, gnat bails out with a
> "gnat bug detected". Compiling normally it goes ok...
>
> Pretty bad luck.

Is this the same as Debian bug #267788?  See here:

http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=267788

-- 
Ludovic Brenta.

Re: Problem with -gnatt

[Alex R. Mosteo]

Ludovic Brenta wrote:
> "Alex R. Mosteo" writes:
> 
>>I'm trying now AdaBrowse with a fairly big project of mine and:
>>
>>When I add the -gnatt switch to get the tree, gnat bails out with a
>>"gnat bug detected". Compiling normally it goes ok...
>>
>>Pretty bad luck.
> 
> 
> Is this the same as Debian bug #267788?  See here:
> 
> http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=267788

I don't think so. It bails out in a storage error in the instance of one 
of the new AI.302 containers which I'm using in place of Charles. See:

+===========================GNAT BUG DETECTED==============================+
| 3.15p  (20020523) (i686-pc-linux-gnu) Storage_Error stack overflow (or 
erroneous memory access)|
| Error detected at ../../containers/a-cohama.adb:508:4 
[../download/adagio-download-slot.ads:78:4]|

Should I report the bug? I'm not customer of ACT so I don't have 
customer number, for example.

Maybe the use of the Ada.Containers is a practice of risk? ;)

Re: Problem with -gnatt

[Martin Dowie]

Alex R. Mosteo wrote:
> I don't think so. It bails out in a storage error in the instance of
> one of the new AI.302 containers which I'm using in place of Charles. See:
>
> +===========================GNAT BUG
> DETECTED==============================+
>> 3.15p  (20020523) (i686-pc-linux-gnu) Storage_Error stack overflow
>> (or erroneous memory access)| Error detected at
>> ../../containers/a-cohama.adb:508:4
> [../download/adagio-download-slot.ads:78:4]|
>
> Should I report the bug? I'm not customer of ACT so I don't have
> customer number, for example.
>
> Maybe the use of the Ada.Containers is a practice of risk? ;)

I'm guessing that "adagio-download-slot.ads:78" is a new instance of the
hash map container? Is it also nested within a package spec? If so, try
moving it to be at library level and with it back into the original, parent
package...

Cheers

-- Martin

Re: Problem with -gnatt

[Alex R. Mosteo]

Martin Dowie wrote:
> Alex R. Mosteo wrote:
> 
>>I don't think so. It bails out in a storage error in the instance of
>>one of the new AI.302 containers which I'm using in place of Charles. See:
>>
>>+===========================GNAT BUG
>>DETECTED==============================+
>>
>>>3.15p  (20020523) (i686-pc-linux-gnu) Storage_Error stack overflow
>>>(or erroneous memory access)| Error detected at
>>>../../containers/a-cohama.adb:508:4
>>
>>[../download/adagio-download-slot.ads:78:4]|
>>
>>Should I report the bug? I'm not customer of ACT so I don't have
>>customer number, for example.
>>
>>Maybe the use of the Ada.Containers is a practice of risk? ;)
> 
> 
> I'm guessing that "adagio-download-slot.ads:78" is a new instance of the
> hash map container? Is it also nested within a package spec? If so, try
> moving it to be at library level and with it back into the original, parent
> package...

The instantiation was inside the spec of adagio-download-slot.ads, yes. 
I've moved it to a child package at library level and now the error is 
reported there.

I've tried to make a reproducer with an empty program and the 
instantiation, but then it works. ?

Re: Problem with -gnatt

[Stephen Leake]

"Alex R. Mosteo" <devnull@mailinator.com> writes:

> Martin Dowie wrote:
> > Alex R. Mosteo wrote:
> >
> >>I don't think so. It bails out in a storage error in the instance of
> >>one of the new AI.302 containers which I'm using in place of Charles. See:
> >>
> >>+===========================GNAT BUG
> >>DETECTED==============================+
> >>
> >>>3.15p  (20020523) (i686-pc-linux-gnu) Storage_Error stack overflow
> >>>(or erroneous memory access)| Error detected at
> >>>../../containers/a-cohama.adb:508:4
> >>
> >>[../download/adagio-download-slot.ads:78:4]|
> >>
> >>Should I report the bug? I'm not customer of ACT so I don't have
> >>customer number, for example.
> >>
> >>Maybe the use of the Ada.Containers is a practice of risk? ;)
> > I'm guessing that "adagio-download-slot.ads:78" is a new instance of
> > the
> > hash map container? Is it also nested within a package spec? If so, try
> > moving it to be at library level and with it back into the original, parent
> > package...
> 
> The instantiation was inside the spec of adagio-download-slot.ads,
> yes. I've moved it to a child package at library level and now the
> error is reported there.
> 
> I've tried to make a reproducer with an empty program and the
> instantiation, but then it works. ?

Which supports the theory that it is simply a stack overflow.

-- 
-- Stephe

Re: Problem with -gnatt

[Matthew Heaney]

"Stephen Leake" <stephen_leake@acm.org> wrote in message
news:mailman.251.1097331456.390.comp.lang.ada@ada-france.org...
> "Alex R. Mosteo" <devnull@mailinator.com> writes:
>
> >
> > I've tried to make a reproducer with an empty program and the
> > instantiation, but then it works. ?
>
> Which supports the theory that it is simply a stack overflow.

One possibility is that whichever piece of code is using the hashed map is
calling Reserve_Capacity (or one of its older names, Set_Capacity or
Ensure_Capacity) with a very large value, and this raises Storage_Error
because the buckets array is too large.

Re: Problem with -gnatt

[Alex R. Mosteo]

Matthew Heaney wrote:
> "Stephen Leake" <stephen_leake@acm.org> wrote in message
> news:mailman.251.1097331456.390.comp.lang.ada@ada-france.org...
> 
>>"Alex R. Mosteo" <devnull@mailinator.com> writes:
>>
>>
>>>I've tried to make a reproducer with an empty program and the
>>>instantiation, but then it works. ?
>>
>>Which supports the theory that it is simply a stack overflow.
> 
> 
> One possibility is that whichever piece of code is using the hashed map is
> calling Reserve_Capacity (or one of its older names, Set_Capacity or
> Ensure_Capacity) with a very large value, and this raises Storage_Error
> because the buckets array is too large.

This is not a run time problem (well, it is run time for the compiler ;)

Re: Problem with -gnatt

[Ludovic Brenta]

"Alex R. Mosteo" writes:
> Should I report the bug? I'm not customer of ACT so I don't have
> customer number, for example.

Feel free to report it to the Debian bug tracking system once you have
a reproducer.

-- 
Ludovic Brenta.

Re: Problem with -gnatt

[Stephen Leake]

"Alex R. Mosteo" <devnull@mailinator.com> writes:

> Ludovic Brenta wrote:
> > "Alex R. Mosteo" writes:
> >
> >>I'm trying now AdaBrowse with a fairly big project of mine and:
> >>
> >>When I add the -gnatt switch to get the tree, gnat bails out with a
> >>"gnat bug detected". Compiling normally it goes ok...
> >>
> >>Pretty bad luck.
> > Is this the same as Debian bug #267788?  See here:
> > http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=267788
> 
> I don't think so. It bails out in a storage error in the instance of
> one of the new AI.302 containers which I'm using in place of Charles.
> See:
> 
> +===========================GNAT BUG DETECTED==============================+
> | 3.15p  (20020523) (i686-pc-linux-gnu) Storage_Error stack overflow
> (or erroneous memory access)|
> | Error detected at ../../containers/a-cohama.adb:508:4
> [../download/adagio-download-slot.ads:78:4]|
> 
> Should I report the bug? I'm not customer of ACT so I don't have
> customer number, for example.

Perhaps you simply have a stack overflow, and you need to give it more
stack space. That's not a bug in ASIS.

> Maybe the use of the Ada.Containers is a practice of risk? ;)

There may be something about this implementation of Ada.Containers
that is more complex for ASIS to handle then other code you have,
causing it to use more stack space.

At first, always assume the compiler error message is correct, and you
are doing something wrong. With GNAT, that's usually true!

-- 
-- Stephe

Re: Problem with -gnatt

[Jeff C r e e.m]

"Stephen Leake" <stephen_leake@acm.org> wrote in message 
news:mailman.250.1097331421.390.comp.lang.ada@ada-france.org...
> "Alex R. Mosteo" <devnull@mailinator.com> writes:
>
>> Ludovic Brenta wrote:
>> > "Alex R. Mosteo" writes:
>> >
>> >>I'm trying now AdaBrowse with a fairly big project of mine and:
>> >>
>> >>When I add the -gnatt switch to get the tree, gnat bails out with a
>> >>"gnat bug detected". Compiling normally it goes ok...
>> >>
>> >>Pretty bad luck.
>> > Is this the same as Debian bug #267788?  See here:
>> > http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=267788
>>
>> I don't think so. It bails out in a storage error in the instance of
>> one of the new AI.302 containers which I'm using in place of Charles.
>> See:
>>
>> +===========================GNAT BUG 
>> DETECTED==============================+
>> | 3.15p  (20020523) (i686-pc-linux-gnu) Storage_Error stack overflow
>> (or erroneous memory access)|
>> | Error detected at ../../containers/a-cohama.adb:508:4
>> [../download/adagio-download-slot.ads:78:4]|
>>
>> Should I report the bug? I'm not customer of ACT so I don't have
>> customer number, for example.
>
> Perhaps you simply have a stack overflow, and you need to give it more
> stack space. That's not a bug in ASIS.
>
>> Maybe the use of the Ada.Containers is a practice of risk? ;)
>
> There may be something about this implementation of Ada.Containers
> that is more complex for ASIS to handle then other code you have,
> causing it to use more stack space.
>
> At first, always assume the compiler error message is correct, and you
> are doing something wrong. With GNAT, that's usually true!
>



Even if there is something wrong with the code that is being analyzed, the 
fact that it is caught buy a GNAT BUG DETECTED
handler really says that there is a GNAT bug here too. For example if I feed 
the following into an Ada  compiler

main()
{printf ("hello world\n);
}

I'd like to get a nice error message and not something that looks like the 
compiler died.

Whether the input is valid or invalid code probably changes the priority of 
the bug...but it is still a bug.

And I would report it to Ada Core Tech. directly even though you are not a 
customer. Perhaps you will never hear anything back (it varies) but if they 
think it is real it probably will still get in the queue. 

Re: Problem with -gnatt

[Ludovic Brenta]

"Jeff C r e e.m" writes:
> Even if there is something wrong with the code that is being
> analyzed, the fact that it is caught buy a GNAT BUG DETECTED handler
> really says that there is a GNAT bug here too. [...] Whether the
> input is valid or invalid code probably changes the priority of the
> bug...but it is still a bug.
>
> And I would report it to Ada Core Tech. directly even though you are
> not a customer. Perhaps you will never hear anything back (it
> varies) but if they think it is real it probably will still get in
> the queue.

I agree that a bug box really indicates a bug in GNAT which sould be
reported.  However, if you are not a supported customer, the problem
with reporting directly to Ada Core is that the bug remains invisible
to other users.  If you use GNAT 3.15p, I suggest you report the bug
to the Debian bug tracking system, and I will forward it to Ada Core
if the bug is still there in GCC 3.4.  If you use GCC, report the bug
directly to Bugzilla; the folks at Ada Core monitor this.

-- 
Ludovic Brenta.

Re: Problem with -gnatt

[Stephen Leake]

"Jeff C r e e.m" <jcreem@yahoo.com> writes:

> "Stephen Leake" <stephen_leake@acm.org> wrote in message 
> news:mailman.250.1097331421.390.comp.lang.ada@ada-france.org...
> > "Alex R. Mosteo" <devnull@mailinator.com> writes:
> >
> >> Ludovic Brenta wrote:
> >> > "Alex R. Mosteo" writes:
> >> >
> >> >>I'm trying now AdaBrowse with a fairly big project of mine and:
> >> >>
> >> >>When I add the -gnatt switch to get the tree, gnat bails out with a
> >> >>"gnat bug detected". Compiling normally it goes ok...
> >> >>
> >> >>Pretty bad luck.
> >> > Is this the same as Debian bug #267788?  See here:
> >> > http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=267788
> >>
> >> I don't think so. It bails out in a storage error in the instance of
> >> one of the new AI.302 containers which I'm using in place of Charles.
> >> See:
> >>
> >> +===========================GNAT BUG 
> >> DETECTED==============================+
> >> | 3.15p  (20020523) (i686-pc-linux-gnu) Storage_Error stack overflow
> >> (or erroneous memory access)|
> >> | Error detected at ../../containers/a-cohama.adb:508:4
> >> [../download/adagio-download-slot.ads:78:4]|
> >>
> >> Should I report the bug? I'm not customer of ACT so I don't have
> >> customer number, for example.
> >
> > Perhaps you simply have a stack overflow, and you need to give it more
> > stack space. That's not a bug in ASIS.
> >
> >> Maybe the use of the Ada.Containers is a practice of risk? ;)
> >
> > There may be something about this implementation of Ada.Containers
> > that is more complex for ASIS to handle then other code you have,
> > causing it to use more stack space.
> >
> > At first, always assume the compiler error message is correct, and you
> > are doing something wrong. With GNAT, that's usually true!
> >
> 
> Even if there is something wrong with the code that is being
> analyzed, the fact that it is caught buy a GNAT BUG DETECTED handler
> really says that there is a GNAT bug here too. For example if I feed
> the following into an Ada compiler
> 
> main()
> {printf ("hello world\n);
> }
> 
> I'd like to get a nice error message and not something that looks like the 
> compiler died.

Well, that's true. But it is difficult in general to handle
Storage_Error due to stack overflow; you can't trust _anything_. So in
this particular instance, I would not expect a much better error message.

-- 
-- Stephe

Re: Problem with -gnatt

[Matthew Heaney]

"Stephen Leake" <stephen_leake@acm.org> wrote in message
news:mailman.250.1097331421.390.comp.lang.ada@ada-france.org...
> >
>
> There may be something about this implementation of Ada.Containers
> that is more complex for ASIS to handle then other code you have,
> causing it to use more stack space.

The AI-302 containers use very little stack space.  These are all unbounded
forms, so everything is allocated off the heap.

Re: Problem with -gnatt

[Stephen Leake]

"Matthew Heaney" <mheaney@on2.com> writes:

> "Stephen Leake" <stephen_leake@acm.org> wrote in message
> news:mailman.250.1097331421.390.comp.lang.ada@ada-france.org...
> > >
> >
> > There may be something about this implementation of Ada.Containers
> > that is more complex for ASIS to handle then other code you have,
> > causing it to use more stack space.
> 
> The AI-302 containers use very little stack space.  These are all unbounded
> forms, so everything is allocated off the heap.

You are talking about stack space used by an application built with
AI-302 containers.

I was talking about stack space used by an application built with
GNAT ASIS, _analyzing_ AI-302 containers.

It does get confusing :).

-- 
-- Stephe

Re: Problem with -gnatt

[Matthew Heaney]

"Alex R. Mosteo" <devnull@mailinator.com> wrote in message
news:4166538E.6090907@mailinator.com...
>
> I don't think so. It bails out in a storage error in the instance of one
> of the new AI.302 containers which I'm using in place of Charles. See:

If you have a problem with ada.containers.*, then it's in your interest to
tell me about it.


> +===========================GNAT BUG
DETECTED==============================+
> | 3.15p  (20020523) (i686-pc-linux-gnu) Storage_Error stack overflow (or
> erroneous memory access)|
> | Error detected at ../../containers/a-cohama.adb:508:4
> [../download/adagio-download-slot.ads:78:4]|
>
> Should I report the bug? I'm not customer of ACT so I don't have
> customer number, for example.
>
> Maybe the use of the Ada.Containers is a practice of risk? ;)

Tell me which package you're using.  If you have any other information (line
number, etc), then tell me that too.

Re: Problem with -gnatt

[Matthew Heaney]

"Alex R. Mosteo" <devnull@mailinator.com> wrote in message
news:4166538E.6090907@mailinator.com...
>
>
> +===========================GNAT BUG
DETECTED==============================+
> | 3.15p  (20020523) (i686-pc-linux-gnu) Storage_Error stack overflow (or
> erroneous memory access)|
> | Error detected at ../../containers/a-cohama.adb:508:4
> [../download/adagio-download-slot.ads:78:4]|
>
> Should I report the bug? I'm not customer of ACT so I don't have
> customer number, for example.
>
> Maybe the use of the Ada.Containers is a practice of risk? ;)

Please send me the context (or better yet, the whole file) around line 508
of a-cohama.adb.

If you have adagio-download-slot.ads, then send me that too.

Also send me whatever code you have that calls adagio-download-slot.

Re: Problem with -gnatt

[Alex R. Mosteo]

Matthew Heaney wrote:
> "Alex R. Mosteo" <devnull@mailinator.com> wrote in message
> news:4166538E.6090907@mailinator.com...
> 
>>
>>+===========================GNAT BUG
> 
> DETECTED==============================+
> 
>>| 3.15p  (20020523) (i686-pc-linux-gnu) Storage_Error stack overflow (or
>>erroneous memory access)|
>>| Error detected at ../../containers/a-cohama.adb:508:4
>>[../download/adagio-download-slot.ads:78:4]|
>>
>>Should I report the bug? I'm not customer of ACT so I don't have
>>customer number, for example.
>>
>>Maybe the use of the Ada.Containers is a practice of risk? ;)
> 
> 
> Please send me the context (or better yet, the whole file) around line 508
> of a-cohama.adb.
> 
> If you have adagio-download-slot.ads, then send me that too.
> 
> Also send me whatever code you have that calls adagio-download-slot.

You can browse it all at

a-cohama.adb:
http://deepsix.homeip.net/svn/Adagio%20head/containers/a-cohama.adb

adagio-download-slot.ads:
http://deepsix.homeip.net/svn/Adagio%20head/src/download/adagio-download-slot.ads

Currently I've moved the instantiation to a child package:
http://deepsix.homeip.net/svn/Adagio%20head/src/download/adagio-download-slot-maps.ads

Sole instance of a Map:
http://deepsix.homeip.net/svn/Adagio%20head/src/download/adagio-download-manager.adb

Of course the simplest way to reproduce the error is to check out the 
whole http://deepsix.homeip.net/svn/Adagio%20head/ with subversion and 
issue a

make htmlfull

when inside the /src folder.

but you'll need an unpatched gnat 3.15p in linux (I've not tested this 
error in windows).

Re: Problem with -gnatt

[Matthew Heaney]

"Alex R. Mosteo" <devnull@mailinator.com> wrote in message
news:417377F7.7050506@mailinator.com...
>
> Sole instance of a Map:
>
http://deepsix.homeip.net/svn/Adagio%20head/src/download/adagio-download-manager.adb

Note that protected operations should only execute "for a short time."  Your
Http_Report_Downloads protected operation could take longer than a "short
time," if the map is large.  Consider using a semaphore style lock,
something like:

procedure Http_Report_Downloads (...) is
   Control : Control_Type (Semaphore'Access);
begin
   ... -- safely manipulate map that you now have locked
end;

where Control_Type calls Semaphore.Seize during controlled Initialization,
and calls Semaphore.Release during controlled Finalization.

Also consider using a passive iterator instead of an exaplicit loop.  The
passive iterator is likely to be slightly more efficient than an active
iterator.

Re: Problem with -gnatt

[Alex R. Mosteo]

Matthew Heaney wrote:
> "Alex R. Mosteo" <devnull@mailinator.com> wrote in message
> news:417377F7.7050506@mailinator.com...
> 
>>Sole instance of a Map:
>>
> 
> http://deepsix.homeip.net/svn/Adagio%20head/src/download/adagio-download-manager.adb
> 
> Note that protected operations should only execute "for a short time."  Your
> Http_Report_Downloads protected operation could take longer than a "short
> time," if the map is large.  Consider using a semaphore style lock,
> something like:

I know the RM advice but, is there any special reason why it's better to 
wait for a semaphore instead of a protected object? I don't need 
timeouts nor abort semantics, I'll just wait what it is needed.

> procedure Http_Report_Downloads (...) is
>    Control : Control_Type (Semaphore'Access);
> begin
>    ... -- safely manipulate map that you now have locked
> end;
> 
> where Control_Type calls Semaphore.Seize during controlled Initialization,
> and calls Semaphore.Release during controlled Finalization.

I already have a class like this, but I simply don't like manually 
putting semaphores around except for a good reason. Please enlight me :)

Re: Problem with -gnatt

[Matthew Heaney]

"Alex R. Mosteo" <devnull@mailinator.com> writes:

> I know the RM advice but, is there any special reason why it's better
> to wait for a semaphore instead of a protected object? I don't need
> timeouts nor abort semantics, I'll just wait what it is needed.

I think it has something to do with the overhead of acquiring the lock,
either by boosting the priority of the task executing the protected
action, or because spinlocks are uesd, etc.

You also have to make sure that you don't make any "potentially
blocking" calls during execution of the protected action.  (I don't
think you do in your example, but I didn't study it enough to be sure.)


> I already have a class like this, but I simply don't like manually
> putting semaphores around except for a good reason. Please enlighten
> me :)

What do you have against semaphores?  As long as you arrange for the
semaphore to get released (which you can do using a controlled helper
type, as in my example), then there's no reason not to use a semaphore.

My advice is to follow the RM's advice...

Re: Problem with -gnatt

[Brian May]

>>>>> "Matthew" == Matthew Heaney <matthewjheaney@earthlink.net> writes:

    Matthew> What do you have against semaphores?  As long as you
    Matthew> arrange for the semaphore to get released (which you can

I thought the whole idea of protected types is that they were designed
to prevent this type of mistake (either forgetting to lock semaphore
or forgetting to release it).

Also, I have read that implementing a semaphore using a protected type
isn't very efficient, as protected types weren't designed for this
purpose.

    Matthew> do using a controlled helper type, as in my example),
    Matthew> then there's no reason not to use a semaphore.

This wont prevent mistakes where you forget to lock the semaphore.
-- 
Brian May <bam@snoopy.apana.org.au>

Re: Problem with -gnatt

[Matthew Heaney]

Brian May <bam@snoopy.apana.org.au> writes:

> Also, I have read that implementing a semaphore using a protected type
> isn't very efficient, as protected types weren't designed for this
> purpose.


That may be true, but it doesn't change the fact that the RM says
protected operations should be "short."



>     Matthew> do using a controlled helper type, as in my example),
>     Matthew> then there's no reason not to use a semaphore.
> 
> This won't prevent mistakes where you forget to lock the semaphore.

The Control_Type certainly *will* prevent such mistakes.

Re: Problem with -gnatt

[Alex R. Mosteo]

Matthew Heaney wrote:
> Brian May <bam@snoopy.apana.org.au> writes:

>>    Matthew> do using a controlled helper type, as in my example),
>>    Matthew> then there's no reason not to use a semaphore.
>>
>>This won't prevent mistakes where you forget to lock the semaphore.
> 
> The Control_Type certainly *will* prevent such mistakes.

I think he refers to *locking* and not *unlocking* which is, BTW, my 
principal objection too.

Re: Problem with -gnatt

[Matthew Heaney]

"Alex R. Mosteo" <devnull@mailinator.com> wrote in message 
news:4174BF2F.8050306@mailinator.com...
> Matthew Heaney wrote:
>>
>> The Control_Type certainly *will* prevent such mistakes.
>
> I think he refers to *locking* and not *unlocking* which is, BTW, my 
> principal objection too.

We're not talking generalities here.  We're talking about a very specific 
piece of code.  In that piece of code, you "remembered" to write the http 
logging feature as a protected action.  If you can remember to do that, then 
surely you can "remember" to call a semaphore! What's the difference?

My advice is to stop fighting the language...

Re: Problem with -gnatt

[Alex R. Mosteo]

Matthew Heaney wrote:
> "Alex R. Mosteo" <devnull@mailinator.com> wrote in message 
> news:4174BF2F.8050306@mailinator.com...
> 
>>Matthew Heaney wrote:
>>
>>>The Control_Type certainly *will* prevent such mistakes.
>>
>>I think he refers to *locking* and not *unlocking* which is, BTW, my 
>>principal objection too.
> 
> 
> We're not talking generalities here.  We're talking about a very specific 
> piece of code.  In that piece of code, you "remembered" to write the http 
> logging feature as a protected action.  If you can remember to do that, then 
> surely you can "remember" to call a semaphore! What's the difference?

I coulnd't forget to write that as a protected procedure, since the data 
reported is protected. If I must read it, I must do it inside the 
protected procedure. If I unprotect that collection and start using 
semaphores, nobody will warn me when I forget that a lock is to be 
honored. Furthermore, a second reviewer/coder could easily not notice 
that a lock is required around accesses to that data, or miss a comment 
about it.

> My advice is to stop fighting the language...

And I see your point. It's simply that I don't see the big damage in 
what I'm doing. It's an advice. My service isn't that long. The 
collection will hold at worst a hundred elements.

Maybe I'm abusing the language, but surely not fighting against it 
(IMO). It's not like I were making unchecked_conversions or taking 
'Unrestricted_references all over the place and going the C way. It's 
simply that I prefer a protected than a semaphore. Let's assume said 
report costs a whole one second worst case. The user uses it a couple 
times each hour. And let's assume there are a lot of protected, short 
procedures, that also access that collection. Clearly start using 
semaphores is going down the abstraction level path, and looking for 
problems.

The bottom line is: I'm only degrading the performance abusing the 
protected construction? Or could I get erroneous execution? If there's 
nothing suggesting the later (which I don't believe or I wouldn't be 
arguing about it), I find the cost worth it.

Re: Problem with -gnatt

[Matthew Heaney]

"Alex R. Mosteo" <devnull@mailinator.com> wrote in message 
news:417536DE.3060405@mailinator.com...
>
> I coulnd't forget to write that as a protected procedure, since the data 
> reported is protected. If I must read it, I must do it inside the 
> protected procedure.

That just pushes back the argument.  If you can "remember" to declare the 
data inside a protected object, then surely you can "remember" to guard it 
with a semaphore.


> If I unprotect that collection and start using semaphores, nobody will 
> warn me when I forget that a lock is to be honored.

Who is "me"?  The data in question is inside a package body, and the only 
way to manipulate that data is to use the operations provided by the 
package.  So clearly a client of the package cannot forget to "honor a 
lock," since he sees neither the data nor the semaphore.

Re: Problem with -gnatt

[Alex R. Mosteo]

Matthew Heaney wrote:
> "Alex R. Mosteo" <devnull@mailinator.com> wrote in message 
> news:417536DE.3060405@mailinator.com...
> 
>>I coulnd't forget to write that as a protected procedure, since the data 
>>reported is protected. If I must read it, I must do it inside the 
>>protected procedure.
> 
> 
> That just pushes back the argument.  If you can "remember" to declare the 
> data inside a protected object, then surely you can "remember" to guard it 
> with a semaphore.

Well, for me is a push that I don't like, since it goes from the 
compiler's responsability to mine.

At design time I just say: "this datum is to be thread safe", and I put 
it in a protected. Forget about it. If I say "this datum is to be 
accessed with a semaphore", I must remember everytime. Yes, it is 
localized in the body, but it is still another thing to remember. Let's 
invoke Murphy here ;)

>>If I unprotect that collection and start using semaphores, nobody will 
>>warn me when I forget that a lock is to be honored.
> 
> 
> Who is "me"?  The data in question is inside a package body, and the only 
> way to manipulate that data is to use the operations provided by the 
> package.  So clearly a client of the package cannot forget to "honor a 
> lock," since he sees neither the data nor the semaphore.

"Me", as in the one making the implementation of the package. Of course, 
once it is done and well done, there's no issue.

Re: Problem with -gnatt

[Brian May]

>>>>> "Matthew" == Matthew Heaney <mheaney@on2.com> writes:

    Matthew> That just pushes back the argument.  If you can
    Matthew> "remember" to declare the data inside a protected object,
    Matthew> then surely you can "remember" to guard it with a
    Matthew> semaphore.

Err??

If you put protected data inside a protected object, then you only
have to remember once, when you create it. Once created, you cannot
forget no matter how many times you may refer to it.

If you use semaphores, then you have to remember to lock and unlock
the semaphore every time you access a protected object.

You also have to be careful if you gain two locks (either deliberately
or accidently) at the same time not to cause deadlocks.

    Matthew> Who is "me"?  The data in question is inside a package
    Matthew> body, and the only way to manipulate that data is to use
    Matthew> the operations provided by the package.  So clearly a
    Matthew> client of the package cannot forget to "honor a lock,"
    Matthew> since he sees neither the data nor the semaphore.

True. If the package is simple enough, this might be OK. If the
package is more complicated, I guess you could split it apart into a
separate package that emulates a protected type.

However, as I think I might have said before, I have read that
creating a semaphore using a protected type is inefficient, because
protected types where intended to be much more flexible then
semaphores.
-- 
Brian May <bam@snoopy.apana.org.au>

Re: Problem with -gnatt

[Jeffrey Carter]

Brian May wrote:
> 
> However, as I think I might have said before, I have read that
> creating a semaphore using a protected type is inefficient, because
> protected types where intended to be much more flexible then
> semaphores.

There are places where semaphores are required. One is when exclusive 
control of external resources is required, and different combinations of 
such resources are required in different circumstances. Special 
attention to the order of obtaining and releasing such resources is 
needed to avoid deadlock.

There are three ways to deal with mutual exclusion: semaphores, 
protected objects, and passive tasks. Semaphores should be avoided when 
possible. Passive tasks, the main idiom in Ada 83, have the advantages 
of protected objects without the disadvantages. Potentially blocking 
operations may be made from critical regions in passive tasks, for 
example. The disadvantage of passive tasks is that they are tasks, and 
each operation requires a context switch.

There are places where each approach is preferable.

Note that compilers implementing Annex D provide the package 
Ada.Synchronous_Task_Control, which defines type Suspension_Object, 
which is essentially a binary semaphore (D.10), probably implemented 
more efficiently than using a protected object.

-- 
Jeff Carter
"You've got the brain of a four-year-old boy,
and I bet he was glad to get rid of it."
Horse Feathers
47

Re: Problem with -gnatt

[Dmitry A. Kazakov]

On Sun, 24 Oct 2004 05:45:06 GMT, Jeffrey Carter wrote:

> Brian May wrote:
>> 
>> However, as I think I might have said before, I have read that
>> creating a semaphore using a protected type is inefficient, because
>> protected types where intended to be much more flexible then
>> semaphores.
> 
> There are places where semaphores are required. One is when exclusive 
> control of external resources is required, and different combinations of 
> such resources are required in different circumstances. Special 
> attention to the order of obtaining and releasing such resources is 
> needed to avoid deadlock.
> 
> There are three ways to deal with mutual exclusion: semaphores, 
> protected objects, and passive tasks. Semaphores should be avoided when 
> possible. Passive tasks, the main idiom in Ada 83, have the advantages 
> of protected objects without the disadvantages. Potentially blocking 
> operations may be made from critical regions in passive tasks, for 
> example. The disadvantage of passive tasks is that they are tasks, and 
> each operation requires a context switch.

Right, semaphores are required when the operation has to be performed on 1)
the caller context, but at the same time 2) need to be blocking. But what
does it mean to be blocking? Internally it should call to an entry point of
a task or spin for another semaphore. It means that this or that way there
is another task, maybe a non-Ada task, involved. So theoretically, if all
tasks were visible one could rewrite that using requeue. Practically it
would be almost impossible because of the parameter passing problem of
requeue, and because circular requeues seem to be illegal.

-- 
Regards,
Dmitry A. Kazakov
http://www.dmitry-kazakov.de

Re: Problem with -gnatt

[Jeffrey Carter]

Brian May wrote:

>     Matthew> do using a controlled helper type, as in my example),
>     Matthew> then there's no reason not to use a semaphore.
> 
> This wont prevent mistakes where you forget to lock the semaphore.

Heany is talking about a "safe" semaphore, in which the Initialize 
procedure of a controlled object obtains the semaphore, and the Finalize 
procedure releases it. However, I would only advise using a semaphore in 
cases in which you cannot use a protected object.

-- 
Jeff Carter
"Spam! Spam! Spam! Spam! Spam! Spam! Spam! Spam!"
Monty Python's Flying Circus
53

Re: Problem with -gnatt

[Matthew Heaney]

"Jeffrey Carter" <spam@spam.com> wrote in message 
news:b3jdd.1840$%h1.889@newsread3.news.pas.earthlink.net...
>
>  However, I would only advise using a semaphore in cases in which you 
> cannot use a protected object.

Yes, but that is precisely the debate.

Re: Problem with -gnatt

[Alex R. Mosteo]

Matthew Heaney wrote:
> "Alex R. Mosteo" <devnull@mailinator.com> writes:
> 
>>I know the RM advice but, is there any special reason why it's better
>>to wait for a semaphore instead of a protected object? I don't need
>>timeouts nor abort semantics, I'll just wait what it is needed.
> 
> 
> I think it has something to do with the overhead of acquiring the lock,
> either by boosting the priority of the task executing the protected
> action, or because spinlocks are used, etc.

It isn't that contradictory? If locking is costly in a protected object, 
using it for very frequent, very short actions seems pointless. It 
indeed will suggest to use it for rare, longer occurrences.

What's a spinlock?

> You also have to make sure that you don't make any "potentially
> blocking" calls during execution of the protected action.  (I don't
> think you do in your example, but I didn't study it enough to be sure.)

Yep. I have violated this rule somewhere else, consciously. Does this 
have something to do with the original problem?

>>I already have a class like this, but I simply don't like manually
>>putting semaphores around except for a good reason. Please enlighten
>>me :)
> 
> What do you have against semaphores?  As long as you arrange for the
> semaphore to get released (which you can do using a controlled helper
> type, as in my example), then there's no reason not to use a semaphore.

> My advice is to follow the RM's advice...

I'd follow it blindly if it stated too that /don't/ following the advice 
could lead to program errors. If my memory serves right, that is not the 
case? Since it is simply an advice, I prefer to use a protected where 
all the services but one are short. I don't want to leave the powerful 
protected abstraction only because a sporadic use of one of its 
procedures may be a bit longer (which, furthermore, is still something 
fuzzy).

I'm re-reading the ARM and can not find now the advice we are talking 
about. There is, however, a compelling reason to not use long protected 
subprograms in 9.5.1(19) which is busy waiting. Ucks!

Kind regards,

A. Mosteo.

Re: Problem with -gnatt

[Simon Wright]

"Alex R. Mosteo" <devnull@mailinator.com> writes:

> It isn't that contradictory? If locking is costly in a protected
> object, using it for very frequent, very short actions seems
> pointless. It indeed will suggest to use it for rare, longer
> occurrences.

I suppose you need to time it. There's an (x86) hi-res Time package
inthe Booch Components (BC.Support.High_Resolution_Time, see
http://www.pushface.org/components/bc).

For what it's worth, a mutex implemented using a protected type took
about 20 us on a 400 MHz PowerPC under VxWorks ...

> What's a spinlock?

I think it means to loop until a bit becomes clear, then set it (using
an indivisible test-and-set instruction). Doesn't work if you only
have one CPU of course; but if it does work, and the protected regions
are short (a few tens of instructions, depending), will be quicker
than calling some OS sleep() operation.

-- 
Simon Wright                               100% Ada, no bugs.

Re: Problem with -gnatt

[Alex R. Mosteo]

Simon Wright wrote:
> "Alex R. Mosteo" <devnull@mailinator.com> writes:
> 
> 
>>It isn't that contradictory? If locking is costly in a protected
>>object, using it for very frequent, very short actions seems
>>pointless. It indeed will suggest to use it for rare, longer
>>occurrences.
> 
> 
> I suppose you need to time it. There's an (x86) hi-res Time package
> inthe Booch Components (BC.Support.High_Resolution_Time, see
> http://www.pushface.org/components/bc).
> 
> For what it's worth, a mutex implemented using a protected type took
> about 20 us on a 400 MHz PowerPC under VxWorks ...
> 
> 
>>What's a spinlock?
> 
> 
> I think it means to loop until a bit becomes clear, then set it (using
> an indivisible test-and-set instruction). Doesn't work if you only
> have one CPU of course; but if it does work, and the protected regions
> are short (a few tens of instructions, depending), will be quicker
> than calling some OS sleep() operation.

Didn't know that english term for this. Thanks for the explanation. This 
is indeed a compelling argument, at least for multiprocessor machines.

Re: Javadoc-like for Ada

[Lionel Draghi]

Alex R. Mosteo wrote:
> Hi,
> 
> I'm insterested in some doc generation tool ala javadoc; i.e. that not 
> only creates a listing like gnathtml but also capable of extracting 
> explanations from properly formatted comments in the specification.
> 
> I've heard good things about doxygen and I'm going to review it to see 
> if it's suitable for Ada.
> 
> Any other options I should consider?

http://www.naturaldocs.org/ don't require neither special tags in the 
code, nor ASIS.
Building a doc from your sources, or whatever file that can be displayed 
in a brower is easy.

NaturalDocs is far from being as good as gnathtml/AdaDoc/AdaBrowse to 
extract procedure parameters and so on, but as this is clearly one of 
the most uninterresting thing to put in a doc, I don't care. I can use 
emacs or GPS for this kind of navigation.

On the other hand, NaturalDocs is very good at extracting explanations 
from comments, and this seems generaly much more interresting to me.

-- 
Lionel