From c26d9fefc7be1cc7f03d7f0268e62d5f93ac33ff Mon Sep 17 00:00:00 2001 From: Adrien Maret Date: Tue, 2 Apr 2019 10:08:11 +0200 Subject: [PATCH] CPP/JS: Update offline tools (#269) ## What does this PR do? Updates offline-tools pages for [JS 6](https://deploy-preview-269--kuzzle-doc-v2.netlify.com/sdk-reference/js/6/offline-tools/) and [CPP 1](https://deploy-preview-269--kuzzle-doc-v2.netlify.com/sdk-reference/cpp/1/offline-tools/): - add links to related properties/methods - better organization I didn't update the documentation for Go because we first need to move offline-tools related properties documentation to Kuzzle instead of WebSocket protocol. I didn't update the documentation for Java because we will generate it from CPP --- .../1/essentials/signal-handling/index.md | 41 ++++++++ .../cpp/1/kuzzle/constructor/index.md | 2 +- .../cpp/1/kuzzle/getters/snippets/getters.cpp | 14 +-- .../cpp/1/offline-tools/index.md | 81 ++++++++-------- src/sdk-reference/js/6/offline-tools/index.md | 94 ++++++++++++------- 5 files changed, 150 insertions(+), 82 deletions(-) create mode 100644 src/guide/1/essentials/signal-handling/index.md diff --git a/src/guide/1/essentials/signal-handling/index.md b/src/guide/1/essentials/signal-handling/index.md new file mode 100644 index 000000000..97310225a --- /dev/null +++ b/src/guide/1/essentials/signal-handling/index.md @@ -0,0 +1,41 @@ +--- +layout: full.html.hbs +title: Signal Handling +order: 1000 +--- + +# Signal Handling + +Kuzzle handles certain Unix signals which fit into the following three categories: + + * Abnormal termination + * Normal termination + * Dump report generation + +The code related to signal handling can be seen here : [lib/api/kuzzle.js#L183](https://github.com/kuzzleio/kuzzle/blob/master/lib/api/kuzzle.js#L183) + +## Abnormal termination + +Unix signal names: + * `SIGQUIT` + * `SIGABRT` + * `SIGPIPE` + + These signals are the result of a critical error and will force Kuzzle to shutdown. + When one of the aforementioned Unix signals is detected, Kuzzle will first generate a [dump report]({{ site_base_path }}guide/1/essentials/cli#dump) then shutdown. + +## Normal termination + +Unix signal names: + * `SIGTERM` + * `SIGINT` + + These signals are the result of a request to terminate gracefully. + When one of the aforementioned Unix signals is detected, Kuzzle will refuse new requests, exit the cluster, finish the current request queue then shutdown. + +## Dump report + +Unix signal names: + * `SIGTRAP` + +When one of the aforementioned Unix signals is detected, Kuzzle will generate a dump report and continue to serve requests normally. diff --git a/src/sdk-reference/cpp/1/kuzzle/constructor/index.md b/src/sdk-reference/cpp/1/kuzzle/constructor/index.md index 8841fa713..ac84bc763 100644 --- a/src/sdk-reference/cpp/1/kuzzle/constructor/index.md +++ b/src/sdk-reference/cpp/1/kuzzle/constructor/index.md @@ -44,7 +44,7 @@ Kuzzle SDK instance options. | `auto_replay` | 
bool

(`false`) | Automatically replay queued requests on a `EVENT_RECONNECTED` event | | `auto_resubscribe` | 
bool

(`true`) | Automatically renew all subscriptions on a `EVENT_RECONNECTED` event | | `offline_mode` | 
enum Mode

(`MANUAL`) | Offline mode configuration. `MANUAL` or `AUTO` | -| `queue_ttl` | 
unsigned

(`120000`) | Time a queued request is kept during offline mode, in milliseconds | +| `queue_ttl` | 
unsigned int

(`120000`) | Time a queued request is kept during offline mode, in milliseconds | | `queue_max_size` | 
unsigned long

(`500`) | Number of maximum requests kept during offline mode | | `replay_interval` | 
unsigned long

(`10`) | Delay between each replayed requests, in milliseconds | | `reconnection_delay` | 
unsigned long

(`10000`) | Number of milliseconds between reconnection attempts | diff --git a/src/sdk-reference/cpp/1/kuzzle/getters/snippets/getters.cpp b/src/sdk-reference/cpp/1/kuzzle/getters/snippets/getters.cpp index 8f0441f4b..e6cf3ae0c 100644 --- a/src/sdk-reference/cpp/1/kuzzle/getters/snippets/getters.cpp +++ b/src/sdk-reference/cpp/1/kuzzle/getters/snippets/getters.cpp @@ -1,17 +1,17 @@ -kuzzleio::WebSocket *ws = new kuzzleio::WebSocket("kuzzle"); -kuzzleio::Kuzzle *kuzzle = new kuzzleio::Kuzzle(ws); +auto *ws = new kuzzleio::WebSocket("kuzzle"); +auto *kuzzle = new kuzzleio::Kuzzle(ws); std::string jwt_token = kuzzle->jwt(); -kuzzleio::Protocol *protocol = kuzzle->getProtocol(); +auto *protocol = kuzzle->getProtocol(); -int max_size = kuzzle->queueMaxSize(); +uint32_t max_size = kuzzle->queueMaxSize(); -int queue_ttl = kuzzle->queueTTL(); +uint16_t queue_ttl = kuzzle->queueTTL(); -int replay_interval = kuzzle->replayInterval(); +uint32_t replay_interval = kuzzle->replayInterval(); -int reconnection_delay = kuzzle->reconnectionDelay(); +uint32_t reconnection_delay = kuzzle->reconnectionDelay(); std::string volatile_data = kuzzle->volatiles(); diff --git a/src/sdk-reference/cpp/1/offline-tools/index.md b/src/sdk-reference/cpp/1/offline-tools/index.md index b9a9d7c89..157cebf6d 100644 --- a/src/sdk-reference/cpp/1/offline-tools/index.md +++ b/src/sdk-reference/cpp/1/offline-tools/index.md @@ -7,69 +7,74 @@ order: 100 # Offline tools -The Kuzzle SDK provides a set of properties that help your application to be resilient to the loss of network connection -during its lifespan. +The Kuzzle SDK provides a set of options and methods that helps your application to be resilient to the loss of network connection +during its lifespan. -## offlineQueue +## Constructor options -A read-only array containing the requests queued while the SDK is in the `offline` state (it behaves like a FIFO queue). +These options must be set in the `kuzzleio::options` object when [instantiating a new SDK]({{ site_base_path }}sdk-reference/cpp/1/kuzzle/constructor/#arguments). -## queueMaxSize +### auto_queue -A writable `number` defining the maximun size of the `offlineQueue`. +A `boolean` telling the SDK whether to automatically queue requests during the `offline` state or not. -## queueTTL +Default value: `false` -A writable `number` defining the time in milliseconds a queued request is kept in the `offlineQueue`. +### auto_reconnect -## startQueuing() +A `boolean` telling the SDK whether to automatically reconnect or not to Kuzzle after a connection loss. -Starts the requests queuing. Request will be put in the `offlineQueue` instead of being discarded, until `stopQueuing` is called. -Works only in `offline` state, and if the `autoQueue` option is set to false. Call `playQueue` to send to Kuzzle the -requests in the queue, once the SDK state passes to `online`. Call `flushQueue` to empty the queue without sendint the requests. +Default value: `true` -## stopQueuing() +### auto_replay -Stop queuing the requests. Requests will no more be put in the `offlineQueue`, they will be discarded. -Works only in the `offline` state, and if the `autoQueue` option is set to `false`. +A `boolean` telling the SDK whether to automatically send or not the requests in the `offline_queue` on a +`reconnected` event. -## playQueue() +Default value: `false` -Sends to Kuzzle all the requests in the `offlineQueue`. Works only if the SDK is not in a `offline` state, and if the -`autoReplay` option is set to false. +### auto_resubscribe -## flushQueue() +A `boolean` telling the SDK whether to automatically renew or not all subscriptions on a reconnected event. -Empties the `offlineQueue` without sending the requests to Kuzzle. +Default value: `true` -## autoQueue +### queue_max_size -A writable `boolean` telling the SDK whether to automatically queue requests during the `offline` state or not. +An `unsigned long` defining the maximun size of the `offline_queue`. -## autoReplay +Default value: `500` -A writable `boolean` telling the SDK whether to automatically send or not the requests in the `offlineQueue` on a -`reconnected` event. +### queue_ttl + +An `unsigned int` defining the time in milliseconds a queued request is kept in the `offline_queue`. + +Default value: `120000` + +### reconnection_delay + +A `unsigned long` specifying the time in milliseconds between different reconnection attempts. -## autoReconnect +Default value: `10000` -A writable `boolean` telling the SDK whether to automatically reconnect or not to Kuzzle after a connection loss. +## Methods -## reconnectionDelay +### [flushQueue()]({{ site_base_path }}sdk-reference/cpp/1/kuzzle/flush-queue) -A read-only `number` specifying the time in milliseconds between different reconnection attempts. +Empties the `offline_queue` without sending the requests to Kuzzle. -## autoResubscribe +### [playQueue()]({{ site_base_path }}sdk-reference/cpp/1/kuzzle/play-queue) -A writable `boolean` telling the SDK whether to automatically renew or not all subscriptions on a reconnected event. +Sends to Kuzzle all the requests in the `offline_queue`. Works only if the SDK is not in a `offline` state, and if the +`auto_replay` option is set to false. -## queueFilter +### [startQueuing()]({{ site_base_path }}sdk-reference/cpp/1/kuzzle/start-queuing/) -A writable `Function` called by the SDK each time a `Request` need to be queued. The `Request` is passed as the only argument -to the function and is queued only if the function returns `true`. Use it to define which requests are allowed to be queued. +Starts queuing requests when in `offline` state. Requests will be put in the `offline_queue` array instead of being discarded, until `stopQueuing` is called. +Works only in `offline` state when the `auto_queue` option is set to `false`. Call `playQueue` to send to Kuzzle the +requests in the queue, once the SDK state passes to `online`. Call `flushQueue` to empty the queue without sending the requests. -## offlineQueueLoader +### [stopQueuing()]({{ site_base_path }}sdk-reference/cpp/1/kuzzle/stop-queuing) -A writable `Function` called by the SDK before playing the requests in the `offlineQueue`. This function takes no arguments -and returns an array of `Request` that are added on top of the `offlineQueue`. Use it to inject new requests to be played -before the queue. +Stop queuing the requests. Requests will no more be put in the `offline_queue`, they will be discarded. +Works only in the `offline` state, and if the `auto_queue` option is set to `false`. diff --git a/src/sdk-reference/js/6/offline-tools/index.md b/src/sdk-reference/js/6/offline-tools/index.md index 0d856f08a..1c2044291 100644 --- a/src/sdk-reference/js/6/offline-tools/index.md +++ b/src/sdk-reference/js/6/offline-tools/index.md @@ -7,69 +7,91 @@ order: 400 # Offline tools -The Kuzzle SDK provides a set of properties that help your application to be resilient to the loss of network connection +The Kuzzle SDK provides a set of properties that helps your application to be resilient to the loss of network connection during its lifespan. -## offlineQueue +## Contructor options and properties -A read-only `Array` containing the requests queued while the SDK is in the `offline` state (it behaves like a FIFO queue). +These properties can be set in the `options` object when [instantiating a new SDK]({{ site_base_path }}sdk-reference/js/6/kuzzle/constructor/#arguments). -## queueMaxSize +Some of them are also [writable properties]({{ site_base_path }}sdk-reference/js/6/kuzzle/introduction/#properties) available after SDK instantiation. -A writable `number` defining the maximun size of the `offlineQueue`. +### autoQueue -## queueTTL +A writable `boolean` telling the SDK whether to automatically queue requests during the `offline` state or not. -A writable `number` defining the time in milliseconds a queued request is kept in the `offlineQueue`. +Default value: `false` -## startQueuing() +### autoReconnect -Starts queuing requests when in `offline` state. Request will be put in the `offlineQueue` instead of being discarded, until `stopQueuing` is called. -Works only in `offline` state when the `autoQueue` option is set to `false`. Call `playQueue` to send to Kuzzle the -requests in the queue, once the SDK state passes to `online`. Call `flushQueue` to empty the queue without sending the requests. +A writable `boolean` telling the SDK whether to automatically reconnect or not to Kuzzle after a connection loss. -## stopQueuing() +Default value: *Depends on the Protocol* -Stop queuing the requests. Requests will no more be put in the `offlineQueue`, they will be discarded. -Works only in the `offline` state, and if the `autoQueue` option is set to `false`. +### autoReplay -## playQueue() +A writable `boolean` telling the SDK whether to automatically send or not the requests in the `offlineQueue` on a +`reconnected` event. -Sends to Kuzzle all the requests in the `offlineQueue`. Works only if the SDK is not in a `offline` state, and if the -`autoReplay` option is set to false. +Default value: `false` -## flushQueue() +### autoResubscribe -Empties the `offlineQueue` without sending the requests to Kuzzle. +A writable `boolean` telling the SDK whether to automatically renew or not all subscriptions on a reconnected event. -## autoQueue +Default value: `true` -A writable `boolean` telling the SDK whether to automatically queue requests during the `offline` state or not. +### offlineQueue -## autoReplay +A read-only `Array` containing the requests queued while the SDK is in the `offline` state (it behaves like a FIFO queue). -A writable `boolean` telling the SDK whether to automatically send or not the requests in the `offlineQueue` on a -`reconnected` event. +### offlineQueueLoader -## autoReconnect +A writable `Function` called by the SDK before playing the requests in the `offlineQueue`. This function takes no arguments +and returns an array of `Request` that are added on top of the `offlineQueue`. Use it to inject new requests to be played +before the queue. -A writable `boolean` telling the SDK whether to automatically reconnect or not to Kuzzle after a connection loss. +### queueFilter + +A writable `Function` called by the SDK each time a `Request` need to be queued. The `Request` is passed as the only argument +to the function and is queued only if the function returns `true`. Use it to define which requests are allowed to be queued. -## reconnectionDelay +### queueMaxSize + +A writable `number` defining the maximun size of the `offlineQueue`. + +Default value: `500` + +### queueTTL + +A writable `number` defining the time in milliseconds a queued request is kept in the `offlineQueue`. + +Default value: `120000` + +### reconnectionDelay A read-only `number` specifying the time in milliseconds between different reconnection attempts. -## autoResubscribe +Default value: *Depends on the Protocol* -A writable `boolean` telling the SDK whether to automatically renew or not all subscriptions on a reconnected event. +## Methods -## queueFilter +### [flushQueue()]({{ site_base_path }}sdk-reference/js/6/kuzzle/flush-queue) -A writable `Function` called by the SDK each time a `Request` need to be queued. The `Request` is passed as the only argument -to the function and is queued only if the function returns `true`. Use it to define which requests are allowed to be queued. +Empties the `offlineQueue` without sending the requests to Kuzzle. -## offlineQueueLoader +### [playQueue()]({{ site_base_path }}sdk-reference/js/6/kuzzle/play-queue) -A writable `Function` called by the SDK before playing the requests in the `offlineQueue`. This function takes no arguments -and returns an array of `Request` that are added on top of the `offlineQueue`. Use it to inject new requests to be played -before the queue. +Sends to Kuzzle all the requests in the `offlineQueue`. Works only if the SDK is not in a `offline` state, and if the +`autoReplay` option is set to false. + +### [startQueuing()]({{ site_base_path }}sdk-reference/js/6/kuzzle/start-queuing/) + +Starts queuing requests when in `offline` state. Requests will be put in the `offlineQueue` array instead of being discarded, until `stopQueuing` is called. +Works only in `offline` state when the `autoQueue` option is set to `false`. Call `playQueue` to send to Kuzzle the +requests in the queue, once the SDK state passes to `online`. Call `flushQueue` to empty the queue without sending the requests. + +### [stopQueuing()]({{ site_base_path }}sdk-reference/js/6/kuzzle/stop-queuing) + +Stop queuing the requests. Requests will no more be put in the `offlineQueue`, they will be discarded. +Works only in the `offline` state, and if the `autoQueue` option is set to `false`.