Manually release all prepared statements on this connection.
While minimal, every prepared statement registered on a connection does
use up a small amount of resources in both mysql-native and on the server.
Additionally, servers can be configured
to limit the number of prepared statements
allowed on a connection at one time (the default, however
is quite high). Note also, that certain overloads of mysql.commands.exec,
mysql.commands.query, etc. register prepared statements behind-the-scenes
which are cached for quick re-use later.
Therefore, it may occasionally be useful to clear out all prepared
statements on a connection, together with all resources used by them (or
at least leave the resources ready for garbage-collection). This function
does just that.
Note that this is ALWAYS COMPLETELY SAFE to call, even if you still have
live prepared statements you intend to use again. This is safe because
mysql-native will automatically register or re-register prepared statements
as-needed.
Notes:
In actuality, the prepared statements might not be immediately released
(although isRegistered will still report false for them).
This is because there could be a mysql.result.ResultRange with results
still pending for retrieval, and the protocol doesn't allow sending commands
(such as "release a prepared statement") to the server while data is pending.
Therefore, this function may instead queue the statement to be released
when it is safe to do so: Either the next time a result set is purged or
the next time a command (such as mysql.commands.query or
mysql.commands.exec) is performed (because such commands automatically
purge any pending results).
This function does NOT auto-purge because, if this is ever called from
automatic resource management cleanup (refcounting, RAII, etc), that
would create ugly situations where hidden, implicit behavior triggers
an unexpected auto-purge.
Manually release all prepared statements on this connection.
While minimal, every prepared statement registered on a connection does use up a small amount of resources in both mysql-native and on the server. Additionally, servers can be configured to limit the number of prepared statements allowed on a connection at one time (the default, however is quite high). Note also, that certain overloads of mysql.commands.exec, mysql.commands.query, etc. register prepared statements behind-the-scenes which are cached for quick re-use later.
Therefore, it may occasionally be useful to clear out all prepared statements on a connection, together with all resources used by them (or at least leave the resources ready for garbage-collection). This function does just that.
Note that this is ALWAYS COMPLETELY SAFE to call, even if you still have live prepared statements you intend to use again. This is safe because mysql-native will automatically register or re-register prepared statements as-needed.
Notes:
In actuality, the prepared statements might not be immediately released (although isRegistered will still report false for them).
This is because there could be a mysql.result.ResultRange with results still pending for retrieval, and the protocol doesn't allow sending commands (such as "release a prepared statement") to the server while data is pending. Therefore, this function may instead queue the statement to be released when it is safe to do so: Either the next time a result set is purged or the next time a command (such as mysql.commands.query or mysql.commands.exec) is performed (because such commands automatically purge any pending results).
This function does NOT auto-purge because, if this is ever called from automatic resource management cleanup (refcounting, RAII, etc), that would create ugly situations where hidden, implicit behavior triggers an unexpected auto-purge.