lastUsedAt() return value
DaveRandom opened this issue · comments
At present the return value of lastUsedAt() is of type int, described as "the timestamp at which was last used".
This has a couple of issues:
- The units of the timestamp are not specified (secs, msecs, usecs)
- If the units are seconds, this does not align with typical amp APIs, which mostly (all?) use milliseconds
- If the units are sub-second, the type
intdoes not play nice with 32 bit systems
I propose changing the return type to \DateTimeImmutable or \DateTimeInterface (my personal preference being for the former). This is an unambiguous, portable way to represent an absolute time,
Also worth noting:
Although I raise the idea of sub-second units above, I don't think granularity actually matters here, and it would IMO be fine to specify a minimum granularity of 1 second. This would enable implementations (if they so desire) to use time() internally for tracking and e.g. comparisons in pool GC operations, thus avoiding the overhead of creating a new DateTimeImmutable instance for every operation, and simply convert the internal integer value to an object at the API boundary.
I don't see such advantage of the DateTimeImmutable return value. Most usages will just check for a certain time offset, e.g. lastUsedAt() < time() - 60. We need an absolute timestamp here instead of something that deals with timezones. We could maybe return the idle period instead of the time of last usage, but that'll be less efficient for more connections, as it needs a time() call for each connection instead of one for all connections in the GC.
I've added the time unit to the documentation.