Manually release a prepared statement on this connection.
This method tells the server that it can dispose of the information it
holds about the current prepared statement.
Calling this is not strictly necessary. The server considers prepared
statements to be per-connection, so they'll go away when the connection
closes anyway. This is provided in case direct control is actually needed.
If you choose to use a reference counted struct to call this automatically,
be aware that embedding reference counted structs inside garbage collectible
heap objects is dangerous and should be avoided, as it can lead to various
hidden problems, from crashes to race conditions. (See the discussion at issue
#159
for details.) Instead, it may be better to simply avoid trying to manage
their release at all, as it's not usually necessary. Or to periodically
release all prepared statements, and simply allow mysql-native to
automatically re-register them upon their next use.
Notes:
In actuality, the server might not immediately be told to release the
statement (although isRegistered will still report false).
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 a prepared statement on this connection.
This method tells the server that it can dispose of the information it holds about the current prepared statement.
Calling this is not strictly necessary. The server considers prepared statements to be per-connection, so they'll go away when the connection closes anyway. This is provided in case direct control is actually needed.
If you choose to use a reference counted struct to call this automatically, be aware that embedding reference counted structs inside garbage collectible heap objects is dangerous and should be avoided, as it can lead to various hidden problems, from crashes to race conditions. (See the discussion at issue #159 for details.) Instead, it may be better to simply avoid trying to manage their release at all, as it's not usually necessary. Or to periodically release all prepared statements, and simply allow mysql-native to automatically re-register them upon their next use.
Notes:
In actuality, the server might not immediately be told to release the statement (although isRegistered will still report false).
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.