| 1 |
fb_shutdown(), fb_shutdown_callback() - new API call in Firebird 2.5. |
| 2 |
|
| 3 |
Implements smart shutdown of engine. Primarily used when working with embedded Firebird. |
| 4 |
|
| 5 |
Author: |
| 6 |
Alex Peshkoff <[email protected]> |
| 7 |
|
| 8 |
Syntax is: |
| 9 |
|
| 10 |
typedef int (*FB_SHUTDOWN_CALLBACK)(const int reason, const int mask, void* arg); |
| 11 |
|
| 12 |
int fb_shutdown(unsigned int timeout, |
| 13 |
const int reason); |
| 14 |
|
| 15 |
ISC_STATUS fb_shutdown_callback(ISC_STATUS* status_vector, |
| 16 |
FB_SHUTDOWN_CALLBACK callback_function, |
| 17 |
const int mask, |
| 18 |
void* arg); |
| 19 |
|
| 20 |
Description: |
| 21 |
|
| 22 |
fb_shutdown() performs smart shutdown of various Firebird subsystems (yValve, engine, redirector). |
| 23 |
It DOES NOT perform shutdown of remote servers, to which you are currently attached - just |
| 24 |
terminates any Firebird activity in the current process. fb_shutdown() was primarily designed |
| 25 |
to be used by engine itself, but also can be used in user applications - for example, if you want |
| 26 |
to close all opened handles at once, fb_shutdown() may be used for it. Normally it should not be |
| 27 |
used, because Firebird libraries (both kinds - embedded or pure client) do call it automatically |
| 28 |
at exit(). To make fb_shutdown() be called at exit, you should attach at least one database (or |
| 29 |
service). |
| 30 |
|
| 31 |
fb_shutdown() accepts 2 parameters - timeout in milliseconds and reason of shutdown. Engine uses |
| 32 |
negative reason codes (they are listed in ibase.h, see constants starting with fb_shutrsn), if |
| 33 |
you need to call fb_shutdown() from your program, you must use positive value for reason. This |
| 34 |
value is passed to callback_function, passed as an argument to fb_shutdown_callback(), and you can |
| 35 |
take appropriate actions when writing callback function. |
| 36 |
|
| 37 |
Zero return value of fb_shutdown() means shutdown is successfull, non-zero means some errors took |
| 38 |
place during shutdown. You should consult firebird.log for more information. |
| 39 |
|
| 40 |
fb_shutdown_callback() setups callback function, which will be called during shutdown. It has 4 |
| 41 |
parameters - status vector, pointer to callback function, call mask and argumnet to be passed |
| 42 |
to callback function. Call mask can have the following values: |
| 43 |
fb_shut_confirmation - callback function may return non-zero value to abort shutdown |
| 44 |
fb_shut_preproviders - callback function will be called before shutting down engine |
| 45 |
fb_shut_postproviders - callback function will be called after shutting down engine |
| 46 |
fb_shut_finish - final step, callback function may wait for some activity to be terminated |
| 47 |
or ORed combination of them (to make same function be called in required cases). |
| 48 |
Non-zero mask passed to callback will be ORed with mask used in previous call (if any). Mask also |
| 49 |
may have special value 0 - in that case previous mask is reset and callback will never be called. |
| 50 |
|
| 51 |
Callback function has 3 parameters - reason of shutdown, actual value of mask with which it was |
| 52 |
called and argument passed by user to fb_shutdown_callback(). There are 2 specially interesting |
| 53 |
shutdown reasons: |
| 54 |
fb_shutrsn_exit_called - Firebird is closing due to exit() or unloaded client/embedded library |
| 55 |
fb_shutrsn_signal - signal SIGINT or SIGTERM was caught (posix only) |
| 56 |
Second parameter (actual value of mask) helps to distinguish if callback was invoked before or after |
| 57 |
engine shutdown. |
| 58 |
First and second parameters help you decide what action to be taken in your callback. Third can |
| 59 |
be used for any purporse you like and may be NULL. |
| 60 |
|
| 61 |
Zero return value of callback function means it performed it's job OK, non-zero is interpreted |
| 62 |
depending upon call mask. For fb_shut_confirmation non-zero means that shutdown will not be |
| 63 |
performed. It's bad idea to return non-zero if shutdown is due to exit() called. In all other cases |
| 64 |
it means some errors took place, and non-zero value will be returned from fb_shutdown(). It's |
| 65 |
callback function's responsibility to notify the world about exact reasons of error return. |
| 66 |
|
| 67 |
fb_shutdown_callback() almost always returns successfully, though in some cases (out of memory |
| 68 |
for example) it can return error. |
| 69 |
|
| 70 |
Sample (it will make your program do not terminate on ctrl-C pressed after attaching databases): |
| 71 |
|
| 72 |
#include <ibase.h> |
| 73 |
|
| 74 |
// callback function for shutdown |
| 75 |
static int ignoreCtrlC(const int reason, const int, void*) |
| 76 |
{ |
| 77 |
return reason == fb_shutrsn_signal ? 1 : 0; |
| 78 |
} |
| 79 |
|
| 80 |
int main(int argc, char *argv[]) |
| 81 |
{ |
| 82 |
ISC_STATUS_ARRAY status; |
| 83 |
if (fb_shutdown_callback(status, ignoreCtrlC, fb_shut_confirmation, 0)) |
| 84 |
{ |
| 85 |
isc_print_status(status); |
| 86 |
return 1; |
| 87 |
} |
| 88 |
// your code continues ... |
| 89 |
} |