Library Level Question

Library Level Question

[Steve Doiel]

What exactly is meant by Library Level

Section 13.10.2 of the LRM gives the following description:

  (22)
  The accessibility level of all library units is called the library level;
a library-level declaration or entity is one whose accessibility level is
the library level.

Does this mean unit specifications? Implementations? Either?
I'm obviously not a language lawyer, but am often able to figure things out
from the LRM.  this has been an exception.

My observation has been that when I try to take the address ('access) of a
function or procedure that is defined within my main procedure, I get a
message about the wrong library level.  But if I take the address of a
function or procedure defined inside a package spec or body, the compiler is
happy.

Please respond in layman terms (if possible).

SteveD

Re: Library Level Question

[David C. Hoos, Sr.]

Steve Doiel wrote in message <36c853cb.0@news.pacifier.com>...
>What exactly is meant by Library Level
>
>Section 13.10.2 of the LRM gives the following description:
>
>  (22)
>  The accessibility level of all library units is called the library level;
>a library-level declaration or entity is one whose accessibility level is
>the library level.
>
>Does this mean unit specifications? Implementations? Either?
>I'm obviously not a language lawyer, but am often able to figure things out
>from the LRM.  this has been an exception.
>
>My observation has been that when I try to take the address ('access) of a
>function or procedure that is defined within my main procedure, I get a
>message about the wrong library level.  But if I take the address of a
>function or procedure defined inside a package spec or body, the compiler is
>happy.
>
Subprograms declared in packages are at library level, as are subprograms
such as your main program itself.  For example, you could call any procedure
eligible to be a main procedure from within any other subprogram, merely by
mentioning the procedure in a context clause (with).  But, subprograms
nested within that main-eligible procedure are not visible outside that
procedure, hence are not at library level.

Any subprogram which does not make use of variables external to it can be
defined by itself in a file -- only the body is required, because the
subprogram body exposed at library level is its own specification.

Here's an example:

--
-- File Name: util-execute_shell_command.adb
--

with Ada.Characters.Latin_1;
with System;
function Util.Execute_Shell_Command
           (The_Command : String) return Integer is
   function Execute
              (The_Command_Address : System.Address) return Integer;
   pragma Import (C, Execute, "system");
   The_Nul_Terminated_Command_String : constant String :=
     The_Command & Ada.Characters.Latin_1.Nul;
begin
   return Execute (The_Nul_Terminated_Command_String'Address);
end Util.Execute_Shell_Command;

So, a unit that has the context clause
"with Util.Execute_Shell_Command;"

can take the 'Access attribute of the Execute_Shell_Command function,
but not the nested Execute function.

Of course the parent package Util must also be present for this example
to work -- e.g.:
--
-- File: util.ads
-- This specification is the parent for all UTIL specifications.
-- UTIL is the subsystem for utilities.
--
package Util is
   pragma Pure (Util);
end Util;

I hope this is both sufficiently "layman's langusge" and clear.

David C. Hoos, Sr.

Re: Library Level Question

[Matthew Heaney]

"Steve Doiel" <nospam_steved@pacifier.com> writes:

> What exactly is meant by Library Level

I think of library level as the most outer scope of a system.

Think of a real library.  All the books in the library are at "library
level."  But if you open one of the books, and look at a diagram, then
the diagram is _not_ at library level, because it's _inside_ the book.

But the book itself is "inside" the library.  All the things we think of
as being inside the library are at library level (say, the things listed
in the card catalog).

In contrast, a diagram is "more nested," because it's inside the book,
not inside the library (and the diagram would not be in the library's
card catalog).


> Section 13.10.2 of the LRM gives the following description:
> 
>   (22)
>   The accessibility level of all library units is called the library level;
> a library-level declaration or entity is one whose accessibility level is
> the library level.
>
> Does this mean unit specifications? Implementations? Either?
> I'm obviously not a language lawyer, but am often able to figure things out
> from the LRM.  this has been an exception.

This just means that when you have a package, not declared in anything
else, as in

package Book is
  ...
end Book;

that it is at library level.  Just like our book.

But if we have a package inside another, like this:

package Book is

  package Diagram is 

  ...
  end Diagram;

...
end Book;


then the inner package is _not_ at library level.  The diagram is in the
book, not the library.

 
> My observation has been that when I try to take the address ('access) of a
> function or procedure that is defined within my main procedure, I get a
> message about the wrong library level.  But if I take the address of a
> function or procedure defined inside a package spec or body, the compiler is
> happy.


Because inside a procedure, you're not at library level, you're inside
something.  Stretching our analogy a bit, it's like trying to give a
reference to a diagram, without having to also refer to the book, and
that's illegal.

You have a couple of choices:

1) Declare the subprogram you want to call via a pointer inside a
   package at library level:

package Book is

   procedure Diagram;

end;

Now you can safely point to subprogram via a pointer.


2) If you're using GNAT, then you can go outside the Official Language
   by using 'Unrestricted_Access.  You are then allowed to point to your
   local subprogram, without any complaints from the compiler.


This "feature" of the language has been debated many times here on
c.l.a.  Go to DejaNews and search for "downward closures" to get more
info.

Re: Library Level Question

[Steve Doiel]

>But if we have a package inside another, like this:
>
>package Book is
>
>  package Diagram is
>
>  ...
>  end Diagram;
>
>...
>end Book;
>
>
>then the inner package is _not_ at library level.  The diagram is in the
>book, not the library.
>

Thank you, I believe the concept of library level is clear to me now.

If I understand correctly, your example is in slight error in that package
Diagram is at the library level, but its contents are not.

SteveD

Re: Library Level Question

[kirk]

In article <36c8d860.0@news.pacifier.com>, "Steve says...
>
>>But if we have a package inside another, like this:
>>

>>package Book is
>>
>>  package Diagram is
>>
>>  ...
>>  end Diagram;
>>
>>...
>>end Book;
>>
>>
>>then the inner package is _not_ at library level.  The diagram is in the
>>book, not the library.
>>
>

>Thank you, I believe the concept of library level is clear to me now.
>
>If I understand correctly, your example is in slight error in that package
>Diagram is at the library level, but its contents are not.
>
 
huh?

package diagram is NOT at library level. That is the whole point of
the example!

Kirk.

Re: Library Level Question

[Steve Doiel]

>>If I understand correctly, your example is in slight error in that package
>>Diagram is at the library level, but its contents are not.
>>
>
>huh?
>
>package diagram is NOT at library level. That is the whole point of
>the example!
>

Back to the example, with a couple of procedures added:

package Book is

  procedure Read is
  begin
  end Read;

  package Diagram is

    procedure Draw ...
  ...
  end Diagram;

...
end Book;

In this example the procedure "Read" is a the library level and the
procedure "Draw" is not at the library level.  Any declarations between
"procedure Read" and "end Read" are not at the library level (only the
interface is at the library level).  Similarly anything between "package
Diagram" and "end Diagram" is not at the library level, but the interface is
at the library level.

Suppose the diagram package were made a generic.  I could create an instance
of the generic since it is at the library level, but I could not see inside
the generic.

If I'm off base, let me know.

SteveD

Re: Library Level Question

[Tucker Taft]

There are several mistaken replies here.

Library unit packages are at library level,
as are all their contents, both spec and body.
You only "leave" library level by going inside
a subprogram, a type, a generic, etc.
You *stay* at the same level when you enter a sub-package.

Accessibility level relates to "lifetime."  The contents
of a package live as long as the package itself.
On the other hand, the declarations inside a subprogram
last only as long as any given *call* on the subprogram,
whereas the subprogram itself lasts as long as the enclosing
scope lives.

-- 
-Tucker Taft   stt@averstar.com   http://www.averstar.com/~stt/
Technical Director, Distributed IT Solutions  (www.averstar.com/tools)
AverStar (formerly Intermetrics, Inc.)   Burlington, MA  USA

Re: Library Level Question

[Robert A Duff]

The explanation below is not quite right.  "Library level" means
anything whose lifetime is essentially forever -- ie it lasts until the
end of the whole program.  A variable (or anything else) can be nested
inside as many packages as you like, and it lasts "forever".  That's
library level.  OTOH, if it's nested inside a procedure, function, or
task, then it's not at library level -- its lifetime ends when the
containing procedure returns, or whatever.

I think "library level" was a poor choice of terms, because it makes
people think of "library unit", which isn't quite right.

Matthew Heaney <matthew_heaney@acm.org> writes:

> This just means that when you have a package, not declared in anything
> else, as in
> 
> package Book is
>   ...
> end Book;
> 
> that it is at library level.  Just like our book.
> 
> But if we have a package inside another, like this:
> 
> package Book is
> 
>   package Diagram is 
> 
>   ...
>   end Diagram;
> 
> ...
> end Book;
> 
> 
> then the inner package is _not_ at library level.  The diagram is in the
> book, not the library.
-- 
Change robert to bob to get my real email address.  Sorry.

Re: Library Level Question

[Matthew Heaney]

Robert A Duff <bobduff@world.std.com> writes:

> The explanation below is not quite right.  "Library level" means
> anything whose lifetime is essentially forever -- ie it lasts until the
> end of the whole program.  A variable (or anything else) can be nested
> inside as many packages as you like, and it lasts "forever".  That's
> library level.  OTOH, if it's nested inside a procedure, function, or
> task, then it's not at library level -- its lifetime ends when the
> containing procedure returns, or whatever.
>
> I think "library level" was a poor choice of terms, because it makes
> people think of "library unit", which isn't quite right.


After I posted that response, I regretted it, because I knew it wasn't
right.

I was thinking of a few years back when I was using the VMS Ada
compiler.  They had a restriction about the location of procedures that
could be exported: they had to be at "library level" (DEC's term). 

What that meant to them was that this was legal:

package P is

  procedure Op (O : T);
  pragma Export (Op);

end P;


But this was illegal:

package P is

  package Nested is

    procedure Op (O : T);
    pragma Export (Op);

  end Nested;

end P;


Ada95 has finally solved these problems; I just need to get my terms
straight.