23.2 Reference counting
As stated before, fz_path
s are reference counted objects. Once one has been created, references can be
created/destroyed using the standard keep/drop conventions:
/* fz_keep_path: Take an additional reference to a path. No modifications should be carried out on a path to which more than one reference is held, as this can cause race conditions. Never throws exceptions. */ fz_path *fz_keep_path(fz_context *ctx, const fz_path *path); /* fz_drop_path: Drop a reference to a path, destroying the path if it is the last reference. Never throws exceptions. */ void fz_drop_path(fz_context *ctx, const fz_path *path);
A path with more than one reference is considered to be ‘frozen’ or ‘immutable’. It is
not safe to modify such a path, as the other holder of a reference to it may not
expect it to be being changed. That is to say that modification operations on paths
are not atomic between threads.
If you have a path that you wish to be able to modify, simply call fz_clone_path
to obtain a reference to a copy of the path that is safe to modify:
/* fz_clone_path: Clone the data for a path. This is used in preference to fz_keep_path when a whole new copy of a path is required, rather than just a shared pointer. This probably indicates that the path is about to be modified. path: path to clone. Throws exceptions on failure to allocate. */ fz_path *fz_clone_path(fz_context *ctx, fz_path *path);