Tracking issue for difficulties using the API in #14208.
Here's a bullet list of issues, and walk through to explain the logic behind each conclusion:
Timers
The exposed APIs of active()/enroll()/unenroll() creates the following issues:
-
Arbitrary objects can be passed to all three of those. Meaning constructors that have already had an async_id assigned would have a conflict.
- Possible solution: Piggy back on the preexisting
async_id and simply not assign a new one, and skip running init().
Conclusion: Not possible because an object that is meant to be assigned an async_id hasn't had it assigned before being passed to active(). Thus assigning one, and firing init() with a type === 'Timeout'.
- Possible solution:
timers has it's own async_id_symbol separate from the one exported by process.binding('async_wrap') and have the object treated as a completely separate asynchronous resource.
Conclusion: Most plausible option, but still fails in a few edge cases as will be discussed.
-
Option [1.2] has the edge case of possibly not being able to acquire the correct trigger_id. For example:
const { async_id_symbol } = process.binding('async_wrap');
const s = new net.Socket();
console.log(s[async_id_symbol] === -1)
s.setTimeout(10, () => {});
Though this case is simple, and the reason for the new API. What happens is the async_id is assigned in net.Socket() and that async_id is passed to TCPWrap.
- issue: Because
init() won't fire until TCPWrap is constructed (which in this case isn't actually until .listen() for net.Server()) users will see async_ids in their graphs that haven't run init() yet.
- issue: More complex cases break down quickly. For example
http.OutgoingMessage() isn't directly attached to the object that has the reference to the TCPWrap instance, but it still has its own setTimeout() method. Making it nearly impossible to pre-assign the async_id and then safely pass it down the object chain to reach TCPWrap.
-
Usage of enroll() is completely optional, since any object can be passed directly to active(), but node internals uses both HandleWrap::Close() and/or unenroll() to close the resource.
Conclusion: Calling destroy() for on the timer's async_id_symbol, an active() object needs to check the following things:
Timeout#close() will emitDestroy() if timer._called === false and if the timer hasn't been unenroll()'d.
- After the
_onTimeout() callback has run, regardless of whether the callback threw or not. If the error is handled then it'll be called later in the event loop. If not then the process is exiting and it didn't matter anyway.
Note: timer._called is set to true before the callback runs, so calling timer.close() during the _onTimeout() callback that value is safe to check in Timeout#close().
unenroll() will emitDestroy() if the timer hasn't been closed, and if timer._called === false.
Note: Part of the problem here is that while you don't need to pass pass a Timeout() instance to active() or enroll() (though you can...) it is possible to pass a Timeout() instance to unenroll(). Which is basically the same as passing it to clearTimeout().
Note: This means assigning the async_id_symbol (thus calling emitInit()) should happen in the call to active, and enroll() should simply be seen as a helper function to add properties to the object. But unenroll() can call emitDestroy(). This makes for a somewhat unintuitive API.
Note: This isn't everything, but is enough to get started. Will update soon with the remainder of the known edge cases.
cc @addaleax @AndreasMadsen @refack
Tracking issue for difficulties using the API in #14208.
Here's a bullet list of issues, and walk through to explain the logic behind each conclusion:
Timers
The exposed APIs of
active()/enroll()/unenroll()creates the following issues:Arbitrary objects can be passed to all three of those. Meaning constructors that have already had an
async_idassigned would have a conflict.async_idand simply not assign a new one, and skip runninginit().Conclusion: Not possible because an object that is meant to be assigned an
async_idhasn't had it assigned before being passed toactive(). Thus assigning one, and firinginit()with atype === 'Timeout'.timershas it's ownasync_id_symbolseparate from the one exported byprocess.binding('async_wrap')and have the object treated as a completely separate asynchronous resource.Conclusion: Most plausible option, but still fails in a few edge cases as will be discussed.
Option [1.2] has the edge case of possibly not being able to acquire the correct
trigger_id. For example:Though this case is simple, and the reason for the new API. What happens is the
async_idis assigned innet.Socket()and thatasync_idis passed toTCPWrap.init()won't fire untilTCPWrapis constructed (which in this case isn't actually until.listen()fornet.Server()) users will seeasync_ids in their graphs that haven't runinit()yet.http.OutgoingMessage()isn't directly attached to the object that has the reference to theTCPWrapinstance, but it still has its ownsetTimeout()method. Making it nearly impossible to pre-assign theasync_idand then safely pass it down the object chain to reachTCPWrap.Usage of
enroll()is completely optional, since any object can be passed directly toactive(), but node internals uses bothHandleWrap::Close()and/orunenroll()to close the resource.Conclusion: Calling
destroy()for on the timer'sasync_id_symbol, anactive()object needs to check the following things:Timeout#close()willemitDestroy()iftimer._called === falseand if the timer hasn't beenunenroll()'d._onTimeout()callback has run, regardless of whether the callback threw or not. If the error is handled then it'll be called later in the event loop. If not then the process is exiting and it didn't matter anyway.Note:
timer._calledis set totruebefore the callback runs, so callingtimer.close()during the_onTimeout()callback that value is safe to check inTimeout#close().unenroll()willemitDestroy()if the timer hasn't been closed, and iftimer._called === false.Note: Part of the problem here is that while you don't need to pass pass a
Timeout()instance toactive()orenroll()(though you can...) it is possible to pass aTimeout()instance tounenroll(). Which is basically the same as passing it toclearTimeout().Note: This means assigning the
async_id_symbol(thus callingemitInit()) should happen in the call toactive, andenroll()should simply be seen as a helper function to add properties to the object. Butunenroll()can callemitDestroy(). This makes for a somewhat unintuitive API.Note: This isn't everything, but is enough to get started. Will update soon with the remainder of the known edge cases.
cc @addaleax @AndreasMadsen @refack