CVS difference for ai05s/ai05-0174-1.txt
--- ai05s/ai05-0174-1.txt 2010/10/19 03:51:18 1.8
+++ ai05s/ai05-0174-1.txt 2010/10/22 00:11:25 1.9
@@ -1,4 +1,4 @@
-!standard D.10.1 (00) 10-10-18 AI05-0174-1/05
+!standard D.10.1 (00) 10-10-21 AI05-0174-1/06
!class Amendment 09-10-23
!status Amendment 2012 10-08-12
!status ARG Approved 10-0-0 10-06-19
@@ -12,8 +12,8 @@
!summary
-A Synchronous_Barrier type is added to allow many tasks to be blocked and be released
-together.
+A Synchronous_Barrier type is added to allow many tasks to be blocked and be
+released together.
!problem
@@ -46,7 +46,7 @@
subtype Barrier_Limit is Positive range 1 .. <implementation-defined>;
- type Synchronous_Barrier (Number_Waiting : Barrier_Limit) is limited private;
+ type Synchronous_Barrier (Release_Threshold : Barrier_Limit) is limited private;
procedure Wait_For_Release (The_Barrier : in out Synchronous_Barrier;
Notified : out Boolean);
@@ -55,11 +55,12 @@
-- not specified by the language
end Ada.Synchronous_Barriers;
-When a variable of type Synchronous_Barrier is created with Number_Waiting = N,
-there are no waiting tasks and the barrier is set to block tasks. When the count
-reaches N, all tasks are simultaneously released and the "Notified" out
-parameter is set to True in an arbitrary one of the callers. All other callers
-result in "Notified" being set to False upon returning from the call.
+When a variable of type Synchronous_Barrier is created with Release_Threshold =
+N, there are no waiting tasks and the barrier is set to block tasks. When the
+number of waiting tasks reaches N, all tasks are simultaneously released and the
+"Notified" out parameter is set to True in an arbitrary one of the callers. All
+other callers result in "Notified" being set to False upon returning from the
+call.
Since it is expected that this functionality will often be mapped to hardware
with a maximum number of release gates in a barrier construct, the maximum
@@ -84,7 +85,7 @@
subtype Barrier_Limit is Positive range 1 .. <implementation-defined>;
- type Synchronous_Barrier (Number_Waiting : Barrier_Limit) is limited private;
+ type Synchronous_Barrier (Release_Threshold : Barrier_Limit) is limited private;
procedure Wait_For_Release (The_Barrier : in out Synchronous_Barrier;
Notified : out Boolean);
@@ -99,7 +100,7 @@
Each call to Wait_For_Release blocks the calling task until the number of
blocked tasks associated with the Synchronous_Barrier object is equal to
-Number_Waiting, at which time all blocked tasks are released. Notified is
+Release_Threshold, at which time all blocked tasks are released. Notified is
set to True for one of the released tasks, and set to False for all other
released tasks.
@@ -107,7 +108,7 @@
implementation defined.
Once all tasks have been released, a Synchronous_Barrier object may be reused to
-block another Number_Waiting number of tasks.
+block another Release_Threshold number of tasks.
As the first step of the finalization of a Synchronous_Barrier, each blocked
task is unblocked and Program_Error is raised at the place of the call to
@@ -182,7 +183,7 @@
procedure Test_Barriers is
Number_Of_Tasks : constant := 1_000;
- Barrier : Barriers.Synchronous_Barrier (Number_Waiting => Number_Of_Tasks);
+ Barrier : Barriers.Synchronous_Barrier (Release_Threshold => Number_Of_Tasks);
task type Worker;
@@ -228,7 +229,7 @@
@b<subtype> Barrier_Limit @b<is> Positive @b<range> 1 .. @ft<@i<implementation-defined>>;
- @b<type> Synchronous_Barrier (Number_Waiting : Barrier_Limit) @b<is limited private>;
+ @b<type> Synchronous_Barrier (Release_Threshold : Barrier_Limit) @b<is limited private>;
@b<procedure> Wait_For_Release (The_Barrier : @b<in out> Synchronous_Barrier;
Notified : @b<out> Boolean);
@@ -243,7 +244,7 @@
Each call to Wait_For_Release blocks the calling task until the number of
blocked tasks associated with the Synchronous_Barrier object is equal to
-Number_Waiting, at which time all blocked tasks are released. Notified is
+Release_Threshold, at which time all blocked tasks are released. Notified is
set to True for one of the released tasks, and set to False for all other
released tasks.
@@ -251,7 +252,7 @@
implementation defined.
Once all tasks have been released, a Synchronous_Barrier object may be reused to
-block another Number_Waiting number of tasks.
+block another Release_Threshold number of tasks.
As the first step of the finalization of a Synchronous_Barrier, each blocked
task is unblocked and Program_Error is raised at the place of the call to
@@ -1199,3 +1200,349 @@
****************************************************************
+From: Randy Brukardt
+Sent: Wednesday, October 20, 2010 6:22 PM
+
+You guys did such a good job agreeing on naming that I thought I'd try again.
+(FYI, I need to give Joyce the list of AIs for WG 9 tomorrow evening, so we have
+to decide this quickly or defer it to our meeting.)
+
+John sent the following comment yesterday:
+
+> type Synchronous_Barrier(
+> Number_Waiting: Barrier_Limit) is private;
+>
+> *** There are a lot of bugs in this AI-174 (see my review). Moreover,
+> Number_Waiting seems the wrong identifier. It is the number to wait for.
+...
+
+I replied:
+
+> OTOH, the name of the discriminant does seem misleading. I think we
+> need to change it. "Number_to_Wait_For" is more accurate, but seems
+> clunky. Does anyone have a better idea? Or do we have to send this
+> back to the ARG to come up with an appropriate name for the
+> discriminant. That seems sad given that there is no semantic change.
+
+Tucker suggested:
+
+>How about something like "Count" or "Task_Count"?
+
+Brad noted:
+
+>For what its worth, the name of the parameter of the POSIX call
+>pthread_barrier_init() is "Count"
+
+Tucker replied:
+
+>That gives a bit of additional weight to using "Count" on the Ada
+interface.
+
+I am now replying:
+
+"Count" seems rather ambiguous to me: count of what? There are two counts
+here: the number of tasks that need to be waiting for a release to happen, and
+the number that are actually waiting. The informal description of the feature in
+the !proposal uses "count" to mean the number of tasks actually waiting.
+(Perhaps rewriting that would be a good idea no matter what we change the name
+to??) I don't think there is any problem with the formal description, however.
+
+Still, I would prefer something a bit more descriptive:
+"Task_Count"
+"Expected_Task_Count"
+"Number_Expected"
+"Number_Tasks_Expected"
+
+Number_Expected is the closest to the current naming, but there seems to be some
+reason to include "Count" in the name.
+
+Could everyone give a preference amongst these 5 (or suggest something better
+still)? Thanks.
+
+Name for discriminant of a Synchronous_Barrier ought to be:
+1) "Count"
+2) "Task_Count"
+3) "Expected_Task_Count"
+4) "Number_Expected"
+5) "Number_Tasks_Expected"
+
+My vote is for 5 or 3, 2 or 4 are "can live with", don't like 1.
+
+****************************************************************
+
+From: Bob Duff
+Sent: Wednesday, October 20, 2010 6:30 PM
+
+I vote for 2. Second choice is 3.
+
+I also vote for doing ARG business by e-mail whenever feasible, rather than
+flying across oceans and continents. ;-)
+
+****************************************************************
+
+From: Gary Dismukes
+Sent: Wednesday, October 20, 2010 7:02 PM
+
+> "Count" seems rather ambiguous to me: count of what? There are two
+> counts
+> here: the number of tasks that need to be waiting for a release to
+> happen, and the number that are actually waiting. The informal
+> description of the feature in the !proposal uses "count" to mean the
+> number of tasks actually waiting. ...
+
+That's backwards: I think you meant to say that the !proposal uses "count" to
+mean the number of task to wait for.
+
+> Could everyone give a preference amongst these 5 (or suggest something
+> better still)? Thanks.
+>
+> Name for discriminant of a Synchronous_Barrier ought to be:
+> 1) "Count"
+> 2) "Task_Count"
+> 3) "Expected_Task_Count"
+> 4) "Number_Expected"
+> 5) "Number_Tasks_Expected"
+
+2 and 3 are OK (I guess I have a small preference for 3, though it's a bit long)
+
+I don't like 4 and 5, and 1 isn't descriptive enough.
+
+****************************************************************
+
+From: Randy Brukardt
+Sent: Wednesday, October 20, 2010 7:21 PM
+
+> That's backwards: I think you meant to say that the !proposal uses
+> "count" to mean the number of task to wait for.
+
+No, I think I have it right. Specifically:
+
+--When a variable of type Synchronous_Barrier is created with Number_Waiting =
+N, --there are no waiting tasks and the barrier is set to block tasks. When the
+count --reaches N, all tasks are simultaneously released and the "Notified" out
+--parameter is set to True in an arbitrary one of the callers. All other callers
+--result in "Notified" being set to False upon returning from the call.
+
+"count" in the second sentence here means "number of tasks waiting", since "N"
+clearly means the number of tasks to wait for (and besides, tha value can't
+change during the life of an object, so it would never "reach" anything).
+
+Probably the best thing here is simply to eliminate "count" from this text
+(replacing it by "number of waiting tasks"), since it is obviously confusing
+(Gary being exhibit A), and besides John also noted he was confused during his
+review.
+
+****************************************************************
+
+From: Steve Baird
+Sent: Wednesday, October 20, 2010 7:20 PM
+
+> I vote for 2. Second choice is 3.
+
+Ditto.
+
+****************************************************************
+
+From: Tucker Taft
+Sent: Wednesday, October 20, 2010 7:41 PM
+
+Task_Count works for me. I don't think adding "expected" helps very much.
+
+****************************************************************
+
+From: Gary Dismukes
+Sent: Wednesday, October 20, 2010 8:18 PM
+
+> No, I think I have it right. Specifically:
+
+Right, for some reason I thought you were using the quoted "count" to refer to
+the discriminant. I should have read more carefully...
+
+> Probably the best thing here is simply to eliminate "count" from this
+> text (replacing it by "number of waiting tasks"), since it is
+> obviously confusing (Gary being exhibit A), and besides John also
+> noted he was confused during his review.
+
+Yeah, prolly so.
+
+****************************************************************
+
+From: Brad Moore
+Sent: Thursday, October 21, 2010 12:24 AM
+
+> "Count" seems rather ambiguous to me: count of what? There are two
+> counts here:
+> the number of tasks that need to be waiting for a release to happen,
+> and the number that are actually waiting.
+
+How about Release_Threshold?
+That seems less ambiguous. It shouldn't get confused with "the number of tasks
+that are actually waiting."
+
+Count, and Task_Count have this problem.
+Number_Expected sounds like a boolean parameter to me as does
+Number_Tasks_Expected. What's a Number_Task?
+
+Number_Expected is also ambiguous. The number of expected what? The number of
+waiting tasks expected to be currently waiting, or the number of tasks still to
+be waiting for , the number of barriers?
+
+Number_Of_Tasks_Expected reads better to me, with only 3 extra characters.
+
+I like Number_Of_Tasks_Expected, Release_Threshold, and choice 3 below better
+than the other choices, I think I favour Release_Threshold. Release_Threshold
+perhaps tells you more, it tells you what happens when the count is reached,
+whereas Number_Of_Tasks_Expected, and Expected_Task_Count just allude to the
+count. Also Release_Threshold is shorter, which can be a virtue. Do you have to
+cross a threshold, or can you just reach a threshold?
+
+If I had to choose between the ones below, then I would pick 3.
+
+****************************************************************
+
+From: Jean-Pierre Rosen
+Sent: Thursday, October 21, 2010 2:09 AM
+
+> My vote is for 5 or 3, 2 or 4 are "can live with", don't like 1.
+
+Ditto, although I find 5 a bit too long. My natural inclination would have been
+"Expected_Count". Brad's idea of "Expected_Threshold" is interesting, but I find
+the word "Threshold" a bit long and extremely prone to misspelling (but maybe
+it's just because I'm not a native English speaker).
+
+"Release_Count" would also be quite acceptable to me.
+
+****************************************************************
+
+From: Stephen Michell
+Sent: Thursday, October 21, 2010 4:11 AM
+
+How about "Release_Count"?
+
+****************************************************************
+
+From: John Barnes
+Sent: Thursday, October 21, 2010 6:55 AM
+
+Release_Threshold is great!! Go for it. Better than all the others.
+
+****************************************************************
+
+From: Erhard Ploedereder
+Sent: Thursday, October 21, 2010 7:15 AM
+
+I'll throw "Number_Needed" or "Count_Needed" is the ring, since it the
+Count_Value needed for the barrier to fire, is it not?
+
+Otherwise, vote for 1, then 4. (The word task can be mistaken, because it does
+include the environment task, which people tend to not see as a task. They are
+wrong, but nevertheless..)
+
+****************************************************************
+
+From: Edmond Schonberg
+Sent: Thursday, October 21, 2010 7:41 AM
+
+>> My vote is for 5 or 3, 2 or 4 are "can live with", don't like 1.
+
+Task_Count works for me.
+
+****************************************************************
+
+From: Brad Moore
+Sent: Thursday, October 21, 2010 8:24 AM
+
+The reason I like "Threshold" better than "Count" is that Count to me suggests a
+dynamic running total, that is not associated with a specific point in time.
+"Threshold" suggests a number that must be reached in order for something to
+happen, which also implies a specific point in time, which to me better matches
+the semantics of this thing.
+
+****************************************************************
+
+From: Bob Duff
+Sent: Thursday, October 21, 2010 8:51 AM
+
+> Release_Threshold is great!! Go for it. Better than all the others.
+
+I agree with John.
+
+Release_Threshold wasn't on the ballot when I voted, but if I'm allowed to
+change my vote, I'd like to vote for this new write-in candidate.
+
+****************************************************************
+
+From: Randy Brukardt
+Sent: Thursday, October 21, 2010 1:06 PM
+
+So do I. Does anyone else want to change their vote? I've got 4 in favor of and
+1 against "Release_Threshold". Otherwise it appears that (3)
+"Expected_Task_Count" is ahead. I'll use one or the other, please tell me which.
+
+****************************************************************
+
+From: Randy Brukardt
+Sent: Thursday, October 21, 2010 1:11 PM
+
+...
+> Ditto, although I find 5 a bit too long. My natural inclination would
+> have been "Expected_Count". Brad's idea of "Expected_Threshold" is
+> interesting, but I find the word "Threshold" a bit long and extremely
+> prone to misspelling (but maybe it's just because I'm not a native
+> English speaker).
+
+You're looking at it the wrong way. This is another opportunity presented by Ada
+to learn how to spell a word that you don't commonly use (or always misspell).
+Ada has been great at that: "progenitor", "elaboration", "finalize",
+"initialization", and of course the most misspelled word in English "separate"
+(which Ada went so far as to make a KEYWORD!). So "Threshold" fits into Ada
+history perfectly! :-)
+
+****************************************************************
+
+From: Tucker Taft
+Sent: Thursday, October 21, 2010 1:24 PM
+
+I am happy to shift my vote to "Release_Threshold", and I enjoy learning how to
+spell new words... ;-)
+
+****************************************************************
+
+From: Steve Baird
+Sent: Thursday, October 21, 2010 1:24 PM
+
+> Does anyone else want to change their vote?
+
+Sure. I don't feel strongly about it, but I agree with John and Bob.
+
+****************************************************************
+
+From: Edmond Schonberg
+Sent: Thursday, October 21, 2010 1:27 PM
+
+My problem with Threshold is that it hints at a lower bound, while the
+requirement here is exact match. I stick with Task_Count.
+
+****************************************************************
+
+From: Erhard Ploedereder
+Sent: Thursday, October 21, 2010 3:22 PM
+
+> Release_Threshold is great!! Go for it. Better than all the others.
+
+Agree. (My earlier mail overlapped.)
+
+****************************************************************
+
+From: Randy Brukardt
+Sent: Thursday, October 21, 2010 6:46 PM
+
+So the vote seems to be
+In favor of Release_Threshold 7 (Erhard, Randy, Steve B., John, Brad, Bob,
+Tucker); Against Release_Threshold 2 (Jean-Pierre, Ed)
+
+That seems to be about as clear as these straw polls ever get. So I'll change
+the discriminant to Release_Threshold and send the AI to WG 9. Thanks for the
+input.
+
+****************************************************************
Questions? Ask the ACAA Technical Agent