Skip to content

Commit

Permalink
Merge pull request #914 from Lorak-mmk/session-usage-recommendations
Browse files Browse the repository at this point in the history
Docs: Add recommendations about Session usage.
  • Loading branch information
piodul authored Jan 24, 2024
2 parents 2d8cd7b + f359ed1 commit 4feb6fb
Show file tree
Hide file tree
Showing 2 changed files with 64 additions and 10 deletions.
19 changes: 19 additions & 0 deletions docs/source/connecting/connecting.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,9 +35,28 @@ async fn main() -> Result<(), Box<dyn Error>> {
After successfully connecting to some specified node the driver will fetch topology information about
other nodes in this cluster and connect to them as well.

## Best practices for using Session

:::{warning}
Always try to use only a single Session object per apllication because creating them is very expensive!
:::

The driver maintains its own pool of connections to each node and each connection is capable of handling multiple requests in parallel. Driver will also route requests to nodes / shards that actually own the data (unless the load balancing policy that you use doesn't support it).

For those reasons, we recommend using one instance of `Session` per application.

Creating short-lived `Session`'s (e.g. `Session` per request) is strongly discouraged because it will result in great performance penalties because creating a `Session` is a costly process - it requires estabilishing a lot of TCP connections.
Creating many `Session`'s in one application (e.g. `Session` per thread / per Tokio task) is also discouraged, because it wastes resources - as mentioned before, `Session` maintains a connection pool itself and can handle parallel queries, so you would be holding a lot of connections unnecessarily.

If you need to share `Session` with different threads / Tokio tasks etc. use `Arc<Session>` - all methods of `Session` take `&self`, so it doesn't hinder the functionality in any way.

## Metadata

The driver refreshes the cluster metadata periodically, which contains information about cluster topology as well as the cluster schema. By default, the driver refreshes the cluster metadata every 60 seconds.
However, you can set the `cluster_metadata_refresh_interval` to a non-negative value to periodically refresh the cluster metadata. This is useful when you do not have unexpected amount of traffic or when you have an extra traffic causing topology to change frequently.

## Scylla Cloud Serverless

Scylla Serverless is an elastic and dynamic deployment model. When creating a `Session` you need to
specify the secure connection bundle as follows:

Expand Down
55 changes: 45 additions & 10 deletions docs/sphinx_preprocessor.py
Original file line number Diff line number Diff line change
@@ -1,20 +1,55 @@
import json
import sys

def remove_sphinx_markdown(md_file_text):
text_split = md_file_text.split("```{eval-rst}")

result = text_split[0]
def remove_sphinx_markdown(md_file_text, name):
output_lines = []
skipped_sections = []

in_eval_rst = False
rst_section_content = []

for line in md_file_text.splitlines():
if in_eval_rst:
rst_section_content.append(line)
if line.startswith("```"):
skipped_sections.append('\n'.join(rst_section_content))
rst_section_content = []
in_eval_rst = False
continue

if line.startswith("```{eval-rst}"):
rst_section_content.append(line)
in_eval_rst = True
continue

# mdbook doesn't support other types of admonitions
if line == ":::{warning}":
line = '<div class="warning">'
elif line == ":::":
line = '</div>'

for i in range(1, len(text_split)):
cur_chunk = text_split[i]
result += cur_chunk[cur_chunk.find("```") + 3:]
if line.startswith(':::'):
print(f"Unknown admonition marker in chapter {name}: {line}", file=sys.stderr)
sys.exit(1)

return result

output_lines.append(line)

if len(rst_section_content) > 0:
print(f'Found unclosed rst section in chapter {name}', file=sys.stderr)
sys.exit(1)

if len(skipped_sections) > 0:
print(f"Skipped sections in chapter \"{name}\":", file=sys.stderr)
for section in skipped_sections:
print(section, file=sys.stderr)

return '\n'.join(output_lines)

def process_section(section):
if 'Chapter' in section:
section['Chapter']['content'] = remove_sphinx_markdown(section['Chapter']['content'])
print(f'Processing chapter {section['Chapter']['name']}', file=sys.stderr)
section['Chapter']['content'] = remove_sphinx_markdown(section['Chapter']['content'], section['Chapter']['name'])
for s in section['Chapter']['sub_items']:
process_section(s)

Expand All @@ -23,7 +58,7 @@ def process_section(section):
if sys.argv[1] == "supports":
# then we are good to return an exit status code of 0, since the other argument will just be the renderer's name
sys.exit(0)

print('SphinxToMdBook preprocessor running', file=sys.stderr)
# load both the context and the book representations from stdin
context, book = json.load(sys.stdin)

Expand Down

0 comments on commit 4feb6fb

Please sign in to comment.