False comments in prio.h misleading MANY mozilla developers

NEW
Assigned to

Status

NSPR
NSPR
--
major
12 years ago
12 years ago

People

(Reporter: Nelson Bolyard (seldom reads bugmail), Assigned: Wan-Teh Chang)

Tracking

Firefox Tracking Flags

(Not tracked)

Details

(URL)

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

12 years ago
thx, Nelson :-)

Comment 2

12 years ago
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.
You need to log in before you can comment on or make changes to this bug.