Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

C++ API remove mgp::memory usage #1016

Merged
merged 2 commits into from
Nov 3, 2024
Merged

C++ API remove mgp::memory usage #1016

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
164262b
C++ API remove mgp::memory usage
Ignition Oct 16, 2024
63ddf91
Add v2.21.0 required guard usage note
gitbuda Nov 3, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 21 additions & 15 deletions pages/custom-query-modules/cpp/cpp-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,30 +6,36 @@ description: Get your hands on the API documentation for mgp.hpp, covering decla
# Query modules C++ API

This is the API documentation for `mgp.hpp`, which contains declarations of all
functions in the C++ API for implementing query module procedures and functions.
The source file can be found in the Memgraph installation directory, under
`/usr/include/memgraph`.
functions in the C++ API for implementing query module procedures and
functions. The source file can be found in the Memgraph installation directory,
under `/usr/include/memgraph`.

To see how to implement query modules in C++, take a look at
[the example we provided](/custom-query-modules/python/python-example).
To see how to implement query modules in C++, take a look at [the example we
provided](/custom-query-modules/python/python-example).

If you install any C++ modules after running Memgraph, you’ll need to [load
them into Memgraph](/custom-query-modules/manage-query-modules#loading-query-modules) or restart
Memgraph in order to use them.
them into
Memgraph](/custom-query-modules/manage-query-modules#loading-query-modules) or
restart Memgraph in order to use them.

## Functions and procedures

With this API it’s possible to extend your Cypher queries with **functions** and **procedures** with
`AddProcedure` and `AddFunction`.
With this API it’s possible to extend your Cypher queries with **functions**
and **procedures** with `AddProcedure` and `AddFunction`.

The API needs memory access to add procedures and functions, this can be done with either `mgp::MemoryDispatcherGuard guard(memory);` or `mgp::memory = memory;`, where the use of the former is advised since `mgp::memory = memory;` is not thread-safe and will be deprecated in the future.
The API needs memory access to add procedures and functions, this can be done
with `mgp::MemoryDispatcherGuard guard(memory);`. Old code used `mgp::memory =
memory;`, but this is not thread-safe and has been deprecated. v2.18.1 onwards
you should modify your C++ modules and recompile. v2.21 onwards setting
`mgp::memory` will cause a compilation error, so the guard has to be used.

Functions are simple operations that return a single value and can be used in any expression or predicate.

Procedures are more complex computations that may modify the graph, and their output is available to
later processing steps in your query. A procedure may only be run from `CALL` clauses.
The output is a stream of **records** that is made accessible with a `YIELD` clause.
Functions are simple operations that return a single value and can be used in
any expression or predicate.

Procedures are more complex computations that may modify the graph, and their
output is available to later processing steps in your query. A procedure may
only be run from `CALL` clauses. The output is a stream of **records** that is
made accessible with a `YIELD` clause.

### AddProcedure

Expand Down
15 changes: 9 additions & 6 deletions pages/custom-query-modules/cpp/cpp-example.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -392,13 +392,16 @@ void RandomWalk(mgp_list *args, mgp_graph *memgraph_graph, mgp_result *result, m

<Callout type="error">

As `mgp::memory` is a global object, that means all of the procedures and
`mgp::memory` was a global object, that meant all of the procedures and
functions in a single shared library will refer to the same `mgp::memory`
object. As a result, calling such callables simultaneously from multiple threads
will lead to incorrect memory usage. This also includes the case when the same
callable is called from different user sessions. This is a constraint when using
`mgp::memory` so the use of the thread-safe `MemoryDispatcherGuard guard(memory)`
is advised instead.
object. As a result, calling such callables simultaneously from multiple
threads will lead to incorrect memory usage. This also includes the case when
the same callable is called from different user sessions. For some versions of
memgraph this was deprecated and the use of the thread-safe
`MemoryDispatcherGuard guard(memory)` is advised instead. Its has now been
removed and C++ modules should be recompiled for v2.18.1+. v2.21 onwards
setting `mgp::memory` will cause a compilation error, so the guard has to be
used.

</Callout>

Expand Down