Package 'cleancall'

cleancall: C Resource Cleanup via Exit Handlers

Description

Wrapper of .Call() that runs exit handlers to clean up C resources. Helps managing C (non-R) resources while using the R API.

Author(s)

Maintainer: Gábor Csárdi [email protected] (ORCID)

Authors:

• Lionel Henry [email protected]

Other contributors:

• Posit Software, PBC [copyright holder, funder]

See Also

Useful links:

• https://github.com/r-lib/cleancall#readme

• https://r-lib.github.io/cleancall/

• Report bugs at https://github.com/r-lib/cleancall/issues

---

Call a native routine within an exit context

Description

C functions called this way can call the r_call_on_exit() and/or r_call_on_early_exit() functions to establish exit handlers.

Usage

call_with_cleanup(ptr, ...)

Arguments

ptr	A native pointer object.
...	Arguments for the native routine. Handlers installed via r_call_on_exit() are always executed on exit. Handlers installed via r_call_on_early_exit() are only executed on early exit, i.e. not on normal termination.

C API

• ⁠void r_call_on_exit(void (*fn)(void* data), void *data)⁠

  Push an exit handler to the stack. This exit handler is always executed, i.e. both on normal and early exits.

  Exit handlers are executed right after the function called from call_with_cleanup() exits. (Or the function used in r_with_cleanup_context(), if the cleanup context was established from C.)

  Exit handlers are executed in reverse order (last in is first out, LIFO). Exit handlers pushed with r_call_on_exit() and r_call_on_early_exit() share the same stack.

  Best practice is to use this function immediately after acquiring a resource, with the appropriate cleanup function for that resource.

• ⁠void r_call_on_early_exit(void (*fn)(void* data), void *data)⁠

  Push an exit handler to the stack. This exit handler is only executed on early exists, not on normal termination.

  Exit handlers are executed right after the function called from call_with_cleanup() exits. (Or the function used in r_with_cleanup_context(), if the cleanup context was established from C.)

  Exit handlers are executed in reverse order (last in is first out, LIFO). Exit handlers pushed with r_call_on_exit() and r_call_on_early_exit() share the same stack.

  Best practice is to use this function immediately after acquiring a resource, with the appropriate cleanup function for that resource.

• ⁠SEXP r_with_cleanup_context(SEXP (*fn)(void* data), void* data)⁠

  Establish a cleanup stack and call fn with data. This function can be used to establish a cleanup stack from C code.

See Also

The package README file.

---