TIP #456: EXTEND THE C API TO SUPPORT PASSING OPTIONS TO TCP SERVER CREATION 
==============================================================================
 Version:      $Revision: 1.6 $
 Author:       LemonBoy <that.lemon_at_gmail.com>
               lime boy <thatlemon_at_gmail.com>
 State:        Final
 Type:         Project
 Tcl-Version:  8.7
 Vote:         Done
 Created:      Friday, 18 November 2016
 URL:          https://tip.tcl-lang.org456.html
 Post-History: 

-------------------------------------------------------------------------

 ABSTRACT 
==========

 The *Tcl_OpenTcpServer* interface doesn't provide enough flexibility as 
 experienced during the implementation of the scaffolding necessary to 
 support the *SO_REUSEPORT* flag for sockets. This TIP adds that 
 capability through a new API function, *Tcl_OpenTcpServerEx*, that 
 takes extra options. 

 RATIONALE 
===========

 Currently there's no way to pass extra informations to 
 *Tcl_OpenTcpServer* which is the function that does the heavy lifting 
 by wrapping the socket creation and connection phase. 

 For example, during the implementation of a *-reuseport* option for the 
 *socket* command, a roadblock was hit since informing 
 *Tcl_OpenTcpServer* about the presence of the new flag was only 
 possible via hacks such as exploiting the upper unused bits of the port 
 parameter or its sign bit. 

 A clean solution that also paves the way to the implementation of other 
 switches (such as one for the SO_REUSEADDR flag) is to introduce 
 another function named *Tcl_OpenTcpServerEx* whose signature closely 
 matches the *Tcl_OpenTcpServer* but allows passing a set of flags to 
 customize its behaviour. 

 Following the aforementioned changes to the C API the *socket* command 
 is enhanced with two new options allowing the user to take advantage of 
 the newly introduced flags. 

 SPECIFICATION 
===============

 A *Tcl_OpenTcpServerEx* function is introduced with the following 
 signature: 

       Tcl_Channel *Tcl_OpenTcpServerEx*(Tcl_Interp */interp/, const 
       char * /service/, const char */myHost/, unsigned int /flags/, 
       Tcl_TcpAcceptProc */acceptProc/, ClientData /acceptProcData/) 

 Most arguments are identical to *Tcl_OpenTcpServer* with the exception 
 of the /port/ parameter being replaced by the /service/ one taking a 
 string instead of an integer. Two entries for the /flags/ bitset are 
 defined by this TIP: 

     * *TCL_TCPSERVER_REUSEADDR* - indicate that the socket flag 
       SO_REUSEADDR (or equivalent) should be set. 

     * *TCL_TCPSERVER_REUSEPORT* - indicate that the socket flag 
       SO_REUSEPORT (or equivalent) should be set. 

 The *Tcl_OpenTcpServer* function is then rewritten to be an alias of 
 *Tcl_OpenTcpServerEx* with the *flags* parameter set by default to 
 TCL_TCPSERVER_REUSEADDR so that we keep the API and behaviour 
 compatible with the previous Tcl versions. 

 As for the Tcl side, the *socket* command gains two new optional 
 switches that are only valid for server sockets: *?-reuseaddr boolean?* 
 and *?-reuseport boolean?*, both accepting a boolean argument to either 
 turn off or on the selected behaviour. 

 REFERENCE IMPLEMENTATION 
==========================

 Please refer to the /tip-456/ branch of the core Tcl repository. 

 BACKWARDS COMPATIBILITY 
=========================

 Since *Tcl_OpenTcpServer* can be easily re-implemented in terms of 
 *Tcl_OpenTcpServerEx* the old behaviour is retained. 

 The *socket* command defaults to *-reuseaddr* set to /yes/ as it was 
 already doing before, the user is now able to turn off this behaviour 
 by using *-reuseaddr no*. 

 COPYRIGHT 
===========

 This document has been placed in the public domain. 

-------------------------------------------------------------------------

 TIP AutoGenerator - written by Donal K. Fellows