363114 - False comments in prio.h misleading MANY mozilla developers

Status: NEW

(NSPR :: NSPR, defect)

Description

[Nelson Bolyard (seldom reads bugmail)]

The block comments in prio.h contain many statements that bear the words
"will block" or "blocks".  It appears to me that ALL THESE STATEMENTS ARE 
FALSE on non-blocking sockets.

These false statements appear in the comments for PR_Read, PR_Write, 
PR_Writev, PR_Recv, PR_Send, PR_RecvFrom, PR_SendTo, and PR_AcceptRead.  
(It's unclear to me whether PR_AcceptRead works on non-blocking sockets.)

These statements have led numerous mozilla developers to conclude that the
functions are blocking, even when the sockets are non-blocking.  Some very
wrong code has been written in mozilla due to the mistaken belief that 
these functions are always blocking, even on non-blocking sockets.  These 
statements need to be fixed ASAP.  

I generally don't think of documentation bugs as being high in priority or
severity, but considering the magnitude of the problems caused by this 
mis-documentation, I think this bug is worthy of P1!

Comment 1

[David :Bienvenu]

thx, Nelson :-)

Comment 2

[Kai Engert (:KaiE:)]

http://www.mozilla.org/projects/nspr/reference/html/priofnc.html

The documentation should probably get fixed, too.

We might want to collect proposals for improved wordings in this bug.

Comment 3

[BugBot [:suhaib / :marco/ :calixte]]

The bug assignee didn't login in Bugzilla in the last 7 months and this bug has severity 'major'.
:KaiE, could you have a look please?
For more information, please visit auto_nag documentation.

Comment 4

[BugBot [:suhaib / :marco/ :calixte]]

The severity field is not set for this bug.
:KaiE, could you have a look please?

For more information, please visit BugBot documentation.

Comment 5

[BugBot [:suhaib / :marco/ :calixte]]

The severity field is not set for this bug.
:KaiE, could you have a look please?

For more information, please visit BugBot documentation.