
Data structures whose refCount is modified by functions in tclIORChan.c
=======================================================================

(1)	ReflectedChannel structure (rcPtr)

    	= argv [argc+2].
      	-------------------------------------------------------------------
      	  argv [0]         - command prefix, placeholder for cmd word
      	  argv [1..argc-3] - command prefix, fixed arguments
      	  argv [argc-2]    - placeholder - method name
      	  argv [argc-1]    - placeholder - channel handle
      	  argv [argc]      - placeholder - method argument 1 - varying, optional
      	  argv [argc+1]    - placeholder - method argument 2 - varying, optional
      	-------------------------------------------------------------------

      	Allocation: NewReflectedChannel().

		cmdpfxObj => listv [0...listc-1] => argv [0...argc-3].
		handleObj = channel handle => argv [listc+1] == argv [argc-1].

		handleObj = NextHandle() result RC=0	(1)

	Release: FreeReflectedChannel().

		n = argc-2. decr 0..n-1 = 0..argc-3
		n+1 = argc-1 = channel handle. decr

	argv [0...argc-3]	@2049 RC++		@2131 RC--
	argv [argc-1]		@2059 RC++ RC=1 (1)	@2138 RC-- deleted

	Not accounted for so far:

		argv[argc-2]	method name.
		argv[argc]	method detail 1.
		argv[argc+1]	method detail 2.

	See InvokeTclMethod() for method name, and ITM + callers for the details.


ChanCreateObjCmd()
	modeObj = DecodeEventMask() @1975 RC=1.

	InvokeTclMethod ( modeObj, NULL ) => resObj
	modeObj @593 RC--               !assumes ITM rc neutral to detail1.
	resObj  @(596|613|626|633) RC-- !assumes ITM rc in (0,1).

***	modeObj - may and may not be deleted in ITM.




TclChanPostEventObjCmd() %% Nothing requiring RC management.
MarshallError()		 %% Nothing requiring RC management.
UnmarshallErrorResult()	 %% Nothing requiring RC management.

TclChanCaughtErrorBypass()

	chanMsgObj	out of	Tcl_GetChannelError()		RC=1 assumed, if defined
	interpMsgObj	out of	Tcl_GetChannelErrorInterp()	RC=1 assumed, if defined

	=> move one to msg, @996 RC ++

	Drop all defined	@1000 RC--
				@1003 RC--

	Which ever was not copied to msgObj is dropped here, the other
	is protected by @996. RC neutral at this point.

	UnmarshallErrorResult()

	msgObj @1016 RC--	Now deleted.


ReflectClose()

	InvokeTclMethod ( NULL, NULL ) => resObj
	resObj @1131 RC-- !assumes ITM rc in (0,1).

ReflectInput()

***	toReadObj = NewInt() @1247,2857 RC=0

	InvokeTclMethod ( toReadObj, NULL ) => resObj

	toReadObj not handled !assumes ITM RC-- cleanup

	resObj @1274,3074 RC-- !assumes ITM rc in (0,1).
	NOTE: In error case resObj saved via Tcl_SetChannelError().

ReflectOutput()

***	bufObj = NewByteArray() @1359,2894 RC=0

	InvokeTclMethod ( bufObj, NULL ) => resObj

	bufObj not handled !assumes ITM RC-- cleanup

	resObj @1399,3074 RC-- !assumes ITM rc in (0,1).
	NOTE: In error case resObj saved via Tcl_SetChannelError().

ReflectSeekWide()
ReflectSeek()

***	offObj  = NewInt()    @1466,2929 RC=0
***	baseObj = NewString() @1467,2930 RC=0

	InvokeTclMethod ( offObj, baseObj ) => resObj

	offObj not handled !assumes ITM RC-- cleanup
	baseObj not handled !assumes ITM RC-- cleanup

	resObj @1486,3074 RC-- !assumes ITM rc in (0,1).
	NOTE: In error case resObj saved via Tcl_SetChannelError().

ReflectWatch()

	maskObj = @{1580,2963} DecodeEventMask() @1975 RC=1.

	InvokeTclMethod ( maskObj, NULL ) => void

	maskObj @1582,2967 RC--  !assumes ITM rc neutral to detail1.

	NOTE: Because of DecodeEventMask returning an RC=1 object it
	      is unclear why the runs talked about in the bug report
	      apparently have an RC=0 object going into ITM in
	      ReflectWatch.

ReflectBlock()

***	blockObj  = NewBoolean()    @1635,2973 RC=0

	InvokeTclMethod ( blockObj, NULL ) => resObj

	blockObj not handled !assumes ITM RC-- cleanup

	resObj @1646,3074 RC-- !assumes ITM rc in (0,1).
	NOTE: In error case resObj saved via Tcl_SetChannelError().

ReflectSetOption()

***	optionObj = NewString() @1706,2985 RC=0
***	valueObj  = NewString() @1707,2986 RC=0

	InvokeTclMethod ( optionObj, valueObj ) => resObj

	optionObj not handled !assumes ITM RC-- cleanup
	valueObj  not handled !assumes ITM RC-- cleanup

	resObj @1713,3074 RC-- !assumes ITM rc in (0,1).
	NOTE: In error case resObj - UnmarshallErrorResult() RC neutral @1710

ReflectGetOption()

***	optionObj = NewString() @(1798,1791,3002) RC=0 (1791: NULL)

	InvokeTclMethod ( optionObj, NULL ) => resObj

	optionObj not handled !assumes ITM RC-- cleanup

	resObj @{1856,1860,3074} RC-- !assumes ITM rc in (0,1).
	NOTE: In error case resObj - UnmarshallErrorResult() RC neutral @1804

EncodeEventMask()	 %% Nothing requiring RC management.

DecodeEventMask()

	Returns new obj @1975 RC=1

NewReflectedChannel()	See above.

NextHandle()

	Tcl_ObjPrintf result RC=0
	=> Handle Obj RC=0 returned.

FreeReflectedChannel()	See above.

InvokeTclMethod( argOne, argTwo )

	!rcPtr->interp.

		The interpreter containing the handler command is
		already gone. Throw an error.

	RC in (0,1)	argOne RC-- @2194 deleted.
	RC in (0,1)	argTwo RC-- @2196 deleted.
	resObj = NewString() RC++ @2186 => RC=1 on return

	Regular

	methObj = NewString(), RC++ @2215 RC=1 <=> argv[argc-2]	RC-- @2294
	argOne => argv[argc-1] RC++ @2225 if not NULL RC in (?) RC-- @2296
	argTwo => argv[argc]   RC++ @2229 if not NULL RC in (?) RC-- @2298

	=> Tcl_EvalObjv -- doesn't handle RC=0, needs RC >= 1 for the
		argv to survive the call.

		resObj = GetObjResult, RC >= 1.
	or	resObj = MarshallError () = Tcl_GetReturnOptions() RC=0
		RC++ @2285

1. resObj	(a)	RC=1	NewString() RC++ @2186
		(b)	RC=?	Tcl_GetObjResult().
		(c)	RC=0	MarshallError () = Tcl_GetReturnOptions()

2. methObj	INTERNAL
		NewString, RC=0, ++@2215, RC=1, EvalObjv, RC>=1, --@2294, RC>=0, maybe deleted

3. argOneObj	(a) CCOC,   modeObj,   RC=1.	RC-- @2194,				deleted.
						RC++ @2225 RC=2, RC-- @2296, RC=1,	kept.
		(b) RWatch, maskObj,   RC=1	s.o.
		(c) RClose, ---------------
		(d) RGOpt,  ---------------
		(e) RIn,    toReadObj, RC=0	RC-- @2194,				deleted.
						RC++ @2225 RC=1, RC-- @2296, RC=0,	deleted.
		(f) ROut,   bufObj,    RC=0
		(g) RSeek,  offObj,    RC=0
		(h) RBlock, blockObj,  RC=0
		(i) RSOpt,  optionObj, RC=0
		(j) RGOpt,  optionObj, RC=0

4. argTwoObj	(a) CCOC,   ---------------
		(b) RClose, ---------------
		(c) RIn,    ---------------
		(d) ROut,   ---------------
		(e) RWatch, ---------------
		(f) RBlock, ---------------
		(g) RGOpt,  ---------------
		(h) RSeek,  baseObj,   RC=0
		(i) RSOpt,  valueObj,  RC=0

ErrnoReturn()				%% Nothing requiring RC management.
GetReflectedChannelMap()		%% Nothing requiring RC management.
DeleteReflectedChannelMap()		%% Nothing requiring RC management.
GetThreadReflectedChannelMap()		%% Nothing requiring RC management.
DeleteThreadReflectedChannelMap()	%% Nothing requiring RC management.

ForwardOpToOwnerTHread()
ForwardProc()

SrcExitProc()		%% Nothing requiring RC management.
ForwardSetObjError()	%% Nothing requiring RC management.


argOneObj
argTwoObj
cmd
maskObj
methObj
modeObj
resObj
