Produce Error Dictionary from 'fconfigure -error'Harald OehlmannHarald Oehlmann$Revision: 1.26 $socket non-blocking {error reporting} {option dictionary}
This TIP proposes a new method which allows to return the error message and the error code of a background socket error (as reported by fconfigure -error), similar to the option dictionaries produced by catch and try and consumed by return.
The error message of a background channel error may be retrieved and cleared by fconfigure channel -error, but there is no access to the error code.
In addition, the error may not be handled in the TCL-like way using catch or try (or just let fail the program).
Specially the new try syntax (see example in the man page) is well suited to handle socket errors. Example:
dHJ5IHtzZXQgaCBbc29ja2V0ICRob3N0ICRwb3J0XX1cdHJhcCB7UE9TSVggRUNPTk5SRUZVU0VEfSB7fSB7ICAgICMgaGFuZGxlIG5vdCBvcGVuIHBvcnQ=fQ==
Drivers mostly use POSIX errors to report issues where the error code is more portable than the error message (AFAIK).
To handle an error by try, the error must be thrown.
We are limited to an option to the command fconfigure, as this is implemented within the driver interface.
Throwing the error would change the semantics of fconfigure and thus should not happen (consensus on the core list). Instead, the new fconfigure operation should return the error message and the error code.
To finally throw the error, an utility function (chan throwerror $h) may be defined in TCL. This is not part of this TIP.
The option fconfigure channel -error should be extended to take an optional argument as follows:
fconfigure channel -error ?errorDictVar?
If the optional argument errorDictVar is given, the following dict is written in the named variable of the caller environment:
if there is no error, it should be set to -code 0 if there is an error, it should be set to -code 1 -errorcode errorCode
This is executed in addition to the standard action of fconfigure channel -error.
Usage example with failing async connect:
JSBzZXQgaCBbY29ubmVjdCAtYXN5bmMgbG9jYWxob3N0IDMwMDAxXQ==ZDAwMDAwYWY=JSBmaWxlZXZlbnQgJGggd3JpdGFibGUge3NldCB4IDF9JSB2d2FpdCB4JSBmY29uZmlndXJlICRoIC1lcnJvciBlcnJvckRpY3Q=Y29ubmVjdGlvbiByZWZ1c2VkJSBzZXQgZXJyb3JEaWN0LWNvZGUgMSAtZXJyb3Jjb2RlIHtQT1NJWCBFQ09OTlJFRlVTRUQge2Nvbm5lY3Rpb24gcmVmdXNlZH19JSBjbG9zZSAkaA==
The following example demonstrates the implementation of chan throwerror eg to throw the error from the provided dict.
cHJvYyB0aHJvd2Vycm9yIHtofSB7ICAgIHNldCBlcnJvck1lc3NhZ2UgW2Zjb25maWd1cmUgJGggLWVycm9yRGljdF0=ICAgIHJldHVybiAtb3B0aW9ucyAkZXJyb3JEaWN0ICRlcnJvck1lc3NhZ2U=fQ==
Revision 1.11 of this TIP proposed to really throw the error. Revision 1.21 of this TIP proposed a new option to return an error dict directly.
The tip is implemented in fossil branch tip-428.
The idea of this semantics and a feasability study is from Reinhard Max.
This document has been placed in the public domain.