!standard 13.13.1(12/5) 19-04-05 AI12-0329-1/01 !standard 13.13.1(13/5) !standard 13.13.1(18/5) !standard 13.13.1(26/5) !class Amendment 19-04-05 !status work item 19-04-05 !status received 19-04-03 !priority Low !difficulty Easy !subject Naming of FIFO_Streams packages !summary The package family is named Storage, with children FIFO and Bounded_FIFO. The interface type is named Storage_Stream_Type. !problem The FIFO_Streams packages seem misnamed: (1) There's nothing about the interface that limits it to FIFO operations. It *is* limited to in-memory operations, so perhaps that property should be emphasized with the name. (2) The use of Unbounded_ is inconsistent with the names used for the containers. (3) Repeating "Streams" in the package names is also inconsistent with the containers (we don't have packages "Vector_Container" and "Tree_Container"). Also, the type FIFO_Stream is inconsistent with the naming of other language-defined stream types, which all end with "Stream_Type". !proposal (See Summary.) !wording ** TBD. (There is quite a bit of wording to change, as Brad noted in his review, but it's not worth anyone's time to reproduce that here, especially before the names are chosen. Ada.Streams.Storage Storage_Stream_Type Ada.Streams.Storage.FIFO Stream_Type Ada.Streams.Storage.Bounded_FIFO Stream_Type !discussion "Unbounded_String" is an exception to the meta-rule that we don't use "Unbounded" in names, but that clearly couldn't have been called "String", so some other name was required. That isn't an issue in this case. Ideally, the names chosen for language-defined packages would work well for both the use-adverse and the use-lovers of the Ada community. Note that everyone has to name the full expanded package name in the context clause, so shorter, less redundant names help everyone. It does pay to repeat some information in the type names, as use-lovers will not have any context to make the name clear. E-Mail discussions seemed to settle on naming this family of packages "Storage" in some way, based on the existing Storage_IO package. We also need to consider the type names, particularly of the interface. Some people preferred to repeat Stream in each of the package names. Your author thinks this is rather redundant (he's sick and tired of having to write Ada.Strings.Unbounded_Strings.Unbounded_String, and this would be worse), but for the record: Ada.Streams.Storage_Streams Storage_Stream_Type Ada.Streams.Storage_Streams.FIFO_Streams Stream_Type Ada.Streams.Storage_Streams.Bounded_FIFO_Streams Stream_Type We also considered "Buffers" rather than "Storage" (but Ada already uses "Storage" for this use), !ASIS [Not sure. It seems like some new capabilities might be needed, but I didn't check - Editor.] !ACATS test ACATS B- and C-Tests are needed to check that the new capabilities are supported. !appendix From: Randy Brukardt Sent: Wednesday, April 3, 2019 1:43 AM Brad's AARM Review says: 13.13.1 (12/5) package Ada.Streams.FIFO_Streams I don't see why the same interface couldn't be used for other types of streams, such as LIFO_Streams. This suggests to me that the top-level abstract package is misnamed. I think it would be much better to name the package as; package Ada.Streams.Stream_Buffers or even better just as package Ada.Streams.Buffers which better captures that these streams are in-memory buffers (without file operations). This truly is a restriction of the package, since the package is Nonblocking and cant be derived to be a Nonblocking=>False package, which would be needed to support file operations. The FIFO property of the interface is just in-name only, since anyone could derive from these packages to create abstractions that are non-FIFO. Then the two child packages could be named more specifically for FIFO semantics package Ada.Streams.Buffers.Bounded_FIFO_Streams and package Ada.Streams.Buffers.FIFO_Streams Which also is more consistent with the naming of the container packages, eg Bounded_Vectors, rather than just Bounded or Unbounded. Also, we dont typically name packages with "Unbounded", there is no Unbounded_Vectors package, so with this renaming, we could remove "Unbounded" from the package name, to also be more consistent with the Ada Containers. ================================== Generally, we don't revisit settled naming decisions. However, Brad makes some good points about the naming (especially about the generality of the base interface, and about the inconsistency with the naming of the containers). I also admit that I've never felt that we had the right names for these packages, but I've stayed silent mainly because I don't have a better alternative. But now is the time to consider if different names would be better, as it will be too late before long. As such, I'd like to take a poll to see if there is any will to discuss the names of these package again. The package names in the advisory list came from the ARG meeting where these names were chosen. It wouldn't surprise me if we ended up with some combination of names if we actually do discuss this. [Editor's note: The actual poll and voting results are not provided here.] **************************************************************** From: Randy Brukardt Sent: Wednesday, April 3, 2019 1:43 AM > Comments: [on the poll ballot - Editor.] Given that all of these packages are under "Streams", there isn't any need for the individual child names to include "Streams". Indeed, that's almost certain to be redundant noise. Even people who *love* use clauses have to give the entire name in the with clause and the use clause. And no one wants to write streams 3 or 4 times! In particular, the vast majority of units will with only one of these packages, so the intermediate names don't matter much. Someone could "use" Ada.Streams and then use the intermediate names in use clauses, I guess, but there wouldn't be much point (why save a handful of characters and make your program harder to understand?). Thus, I prefer relatively short names are every level. For me, who would hardly ever "use" one of these packages, the less redundancy in the full name the better: My_Buffer : Ada.Streams.FIFO_Streams.Unbounded.Stream_Type; -- Current name: 3 Streams. My_Buffer : Ada.Streams.Storage.FIFO.Stream_Type; -- My write-in: 2 streams. My_Buffer : Ada.Streams.Buffers.FIFO_Streams.Stream_Type; -- Brad's name: 3 streams. **************************************************************** From: Steve Baird Sent: Wednesday, April 3, 2019 5:42 PM > Comments: [on the poll ballot - Editor.] These comments may serve mostly as a reminder of why we don't want to reopen this discussion, but I'll press on nonetheless. I agree with Brad that FIFO belongs as part of the names of the concrete packages, not as part of the name of the package that defines the abstract type. The thing that distinguishes the abstract type from its parent is the addition of the Element_Count operation (and the less important Clear operation), so I feel that Counted_Streams makes sense for that package. It's been suggested that we want a name that indicates that no file operations are involved, but (as with the FIFO property) that isn't at all implied by the abstract interface and does not make sense for naming the package that declares the abstract type. Thus, I don't like any of the Buffered_Streams or Storage_Streams proposals. So I am left with only my write-in candidate to vote for. There is more to this than changing the names of the packages: we have to look at the names of the stream types too. It wouldn't make sense, for example, to have a type Ada.Streams.Buffers.FIFO_Stream which is what we would get if all we change is the package name. So we really need a proposal for 3 package names and 3 stream type names . I don't like type names that end in "_Type" (e.g., Stream_Type), but just naming all the types "Stream_Type" is an option. We have formal parameters named "Stream", so we don't want to use that name. I often like plural package names where the package exports a type with a corresponding singular name, as in package Miniature_Cars is type Car is private; ... end Miniature_Cars; or package Horses is type Horse is private; ...; end Horses; So with the package names proposed above, the type names could be Counted_Streams.Counted_Stream Counted_Streams.FIFO_Streams.FIFO_Stream Counted_Streams.Bounded_FIFO_Streams.FIFO_Stream (this proposal follows the example of Vectors and Bounded_Vectors with respect to using the same type name in the bounded and unbounded versions). **************************************************************** From: Randy Brukardt Sent: Wednesday, April 3, 2019 6:13 PM ... >It's been suggested that we want a name that indicates that no file >operations are involved, but (as with the FIFO property) that isn't at >all implied by the abstract interface ... As Brad pointed, it *is* implied by the contracts, which surely are part of the abstract interface. So I tend to disagree on this one. If we decided to change the contracts so that external (blocking) stuff was allowed, then I'd have more sympathy. (There's really no reason that the abstract stream has to be Nonblocking; that's only a requirement of actual packages. Unless you think that someone is going to try (in a nonblocking context) to dispatch through this interface rather than directly binding to the primitives of the specific types -- which seems silly for performance reasons alone.) ... > There is more to this than changing the names of the > packages: we have to look at the names of the stream types too. It > wouldn't make sense, for example, to have a type > Ada.Streams.Buffers.FIFO_Stream > which is what we would get if all we change is the package name. Agreed. I didn't realize that this was even the name of a type, it's clearly wrong regardless of any package naming. I suspect that I forgot to change that name with the others. All other existing streams end with "_Stream_Type" (or are just "Stream_Type"), and consistency alone would say that it should at a minimum be "FIFO_Stream_Type". > So we really need a proposal for 3 package names and 3 stream type > names . I don't like type names that end in "_Type" > (e.g., Stream_Type), but just naming all the types "Stream_Type" is an > option. We have formal parameters named "Stream", so we don't want to > use that name. I understand some people have this perspective, and they should do whatever makes sense for their code in their code, but for the language-defined libraries, I think it is pretty important that we consistently use names. The basic stream type is "Root_Stream_Type", and I'd argue that anything derived from it in the language should be named in a similar style. ... > So with the package names proposed above, the type names could be > Counted_Streams.Counted_Stream > Counted_Streams.FIFO_Streams.FIFO_Stream > Counted_Streams.Bounded_FIFO_Streams.FIFO_Stream I would score these at about a -200. Containing a form of "Stream" four times is madness. Remember that one is going to have to use the full name of the package in a context clause, so you would have something like: with Ada.Streams.Counted_Streams.Bounded_FIFO_Streams; which mentions Streams at least two more times than necessary! The primary reason I would like to reconsider these names is to avoid this madness, not make it worse. **************************************************************** From: Steve Baird Sent: Wednesday, April 3, 2019 6:33 PM > As Brad pointed, it*is* implied by the contracts, which surely are > part of the abstract interface. So I tend to disagree on this one. If > we decided to change the contracts so that external (blocking) stuff > was allowed, then I'd have more sympathy. Good point. So I withdraw my objection to Buffered_Streams. > The basic stream type is "Root_Stream_Type", and I'd argue that > anything derived from it in the language should be named in a similar style. Fair enough. I can live with naming all three types "Stream_Type" (or perhaps FIFO_Stream_Type for the two concrete types; what really matters is that the two should be the same). **************************************************************** From: Richard Wai Sent: Wednesday, April 3, 2019 10:41 PM I note that "storage" has a very clear meaning in Ada, and is also used for very similar ends as a FIFO in the package Ada.Storage_IO. For this reason I strongly agree with Storage_Streams.FIFO and family. The "buffer" terminology is common in the broader computing community, but I think using that here will only blur existing consistency. I for one am a huge proponent of orthogonality. I think the existence of Storage_IO especially makes the case for Storage_Streams. I think the FIFO distinction needs to be kept, because LIFO buffers have their use, as do circular buffers. So simply calling them "Storage_Streams.Unbounded" seems too ambiguous. It should be clear exactly what effect any given Write has on a subsequent Read. I also second the others who commented that the unbounded package is usually the parent of the bounded, and the unbounded is the "original". On a more technical note, it would make a lot of sense to implement these kinds of stream objects with some form of a Storage Pool, which makes the Storage name even more relevant. At the end of the day, we're going to be dealing with Storage_Elements as part-in-parcel of using the Streams "subsystem". **************************************************************** From: Tucker Taft Sent: Wednesday, April 3, 2019 11:55 PM I would agree that "Storage" is better than "Buffer" given the existing Storage_IO. I don't have time to do the full ballot at the moment, and am willing to let Randy and Steve make the decision. **************************************************************** From: Erhard Ploedereder Sent: Friday, April 5, 2019 4:07 AM Some comments: re: parent pkg Buffers. What other child packes are planned for the near future? If none, this is bad; if so, this is good. re: FIFO and queues. I expect that a queue is always FIFO or , such as priority-ordered. A LIFO queue is a stack and hence completely misnamed. So, I doubt the need for the FIFO qualification. Consistency across libraries is important. **************************************************************** From: Brad Moore Sent: Friday, April 5, 2019 9:45 AM > Comments: [on the poll ballot - Editor.] Given that we already have Storage_IO, the Storage_Streams suggestion stands out above all the others, in my mind, while addressing my original concerns. **************************************************************** From: Jeff Cousins Sent: Friday, April 5, 2019 3:14 PM > Comments: [on the poll ballot - Editor.] Though I’m sure Randy and Steve would come up with something sensible. ****************************************************************