Struct ContextRef

Source

pub struct ContextRef(/* private fields */);

Expand description

LLVM Context wrapper

Implementations§

Source §

impl ContextRef

LLVM specific implementations

Source

pub fn context_create() -> Self

Create a new context.

§Safety

Every call to this function should be paired with a call to Self::context_dispose or the context will leak memory.

Source

pub fn get_global_context() -> Self

Retrieves the global context instance.

The global context is particularly convenient instance managed by LLVM itself. It is the default context provided for any operations that require it.

§Safety

Failure to specify the correct context in concurrent environments can lead to data corruption. In general, it is always recommended that each thread of execution attempting to access the LLVM API have its own Context instance, rather than rely on this global context.

§Details

This function wraps the LLVMContextSetDiagnosticHandler function from the LLVM core library. It allows you to set a custom diagnostic handler function (LLVMDiagnosticHandler) that will be invoked when diagnostic messages (such as errors, warnings, or remarks) are generated within the context represented by self. Additionally, an optional diagnostic context (UnsafeMutVoidPtr) can be passed, which can hold user-defined data to be used by the diagnostic handler.

§Parameters

handler: The diagnostic handler function (LLVMDiagnosticHandler) to be set for the context.
diagnostic_context: An opaque pointer (UnsafeMutVoidPtr) that can be passed to the diagnostic handler. This context is typically used to store additional data that the handler might need when processing diagnostics.

Source

pub fn set_diagnostic_handler( &self, handler: LLVMDiagnosticHandler, diagnostic_context: UnsafeMutVoidPtr, )

Set debug diagnostic handler for this context.

§Safety

To provide safe operations wi with diagnostic context should be set:

handler - LLVM diagnostic function (handler)
diagnostic_context - raw pointer for diagnostic NOTE: it’s much safer to use raw pointer in that case than std::ptr::NonNull structs.

Source

pub fn get_diagnostic_handler(&self) -> LLVMDiagnosticHandler

Get the diagnostic handler of this context.

§Details

Retrieves the diagnostic handler associated with the current LLVM context.

This function wraps the LLVMContextGetDiagnosticHandler function from the LLVM core library. It returns the diagnostic handler (LLVMDiagnosticHandler) associated with the context represented by self. The diagnostic handler is a function or callback that is invoked when a diagnostic message (such as an error or warning) is generated during compilation or other LLVM operations.

§Returns

Returns an LLVMDiagnosticHandler representing the diagnostic handler associated with the current LLVM context.

Source

pub fn get_diagnostic_context(&self) -> UnsafeMutVoidPtr

Get the diagnostic context of this context.

§Details

Retrieves the diagnostic context associated with the current LLVM context.

This function wraps the LLVMContextGetDiagnosticContext function from the LLVM core library. It returns a raw pointer wrapped in UnsafeMutVoidPtr that represents the diagnostic context associated with the context represented by self. The diagnostic context can be used to store and retrieve additional information related to diagnostics generated during compilation or other operations.

§Returns

Returns an UnsafeMutVoidPtr representing the diagnostic context associated with the current LLVM context.

§Safety

The returned pointer is unsafe and must be handled with care. Ensure that the pointer is used correctly and that any operations involving the pointer respect the rules of memory safety.

Source

pub fn set_yield_callback( &self, callback: LLVMYieldCallback, opaque_handle: UnsafeMutVoidPtr, )

Set the yield callback function for this context.

#Details

Sets a yield callback for the current LLVM context.

This function wraps the LLVMContextSetYieldCallback function from the LLVM core library. It allows you to set a yield callback function that will be invoked periodically during long-running operations in the context represented by self. Yield callbacks can be used to implement cooperative multitasking, allowing other tasks to run or perform actions such as checking for user interruptions.

§Parameters

callback: The callback function (LLVMYieldCallback) to be invoked periodically during long-running operations.
opaque_handle: An opaque pointer (UnsafeMutVoidPtr) that can be passed to the callback function. This handle is typically used to maintain state or pass additional data to the callback.

Source

pub fn should_discard_value_names(&self) -> bool

Retrieve whether the given context is set to discard all value names.

§Details

Checks whether value names should be discarded in the current LLVM context.

This function wraps the LLVMContextShouldDiscardValueNames function from the LLVM core library. It determines whether the context represented by self is currently set to discard value names. Discarding value names can reduce memory usage and improve performance, but it removes human-readable names for values, which may impact debugging and analysis.

§Returns

Returns true if the context is set to discard value names, otherwise returns false.

Source

pub fn set_discard_value_names(&self, discard: bool)

Set whether the given context discards all value names.

If true, only the names of GlobalValue objects will be available in the IR. This can be used to save memory and runtime, especially in release mode.

§Details

Configures whether value names should be discarded in the current LLVM context.

This function wraps the LLVMContextSetDiscardValueNames function from the LLVM core library. It allows you to enable or disable the discarding of value names within the context represented by self. Discarding value names can reduce memory usage and improve performance, but at the cost of losing human-readable names for values.

§Parameters

discard: A boolean indicating whether to discard value names (true to discard, false to keep them).

§Note

Disabling value name retention can make debugging and analysis more difficult since values will lose their human-readable names.

Source

pub fn context_dispose(&self)

Deinitialize this value and dispose of its resources.

Destroy a context instance. This should be called for every call to self::context_create (LLVMContextCreate()) or memory will be leaked.

§Details

Disposes of the current LLVM context, freeing associated resources.

This function wraps the LLVMContextDispose function from the LLVM core library. It releases the resources associated with the LLVM context represented by self. After calling this function, the context should no longer be used, as it will be in an invalid state.

§Safety

This function should be called when you are done using the context to ensure that all resources are properly freed.

Source

pub fn get_md_kind_id_in_context(&self, name: &str) -> MetadataKindId

Get Metadata KindId by name in current Context. Useful for working with Metadata.

§Details

Retrieves the metadata kind ID by name within the current context.

This function simplifies the retrieval of a metadata kind ID by wrapping the get_md_kind_id_in_context method from MetadataKindId. It returns the metadata kind ID corresponding to the provided name within the context represented by self. This is useful for working with metadata in LLVM IR.

§Parameters

name: A string slice (&str) representing the name of the metadata kind.

§Returns

Returns a MetadataKindId representing the ID associated with the provided metadata kind name in the current context.

Source

pub fn create_enum_attribute(&self, kind_id: u32, val: u64) -> AttributeRef

Create an enum attribute.

§Details

Creates an enum attribute within the current LLVM context or module.

This function simplifies the creation of an enum attribute by wrapping the create_enum_attribute method from AttributeRef. It creates an enum attribute with the specified kind ID and value within the context or module represented by self.

§Parameters

kind_id: A u32 representing the kind ID of the enum attribute. This ID specifies the kind of the attribute.
val: A u64 representing the value of the enum attribute.

§Returns

Returns an AttributeRef representing the created enum attribute.

Source

pub fn create_type_attribute( &self, kind_id: u32, type_ref: &TypeRef, ) -> AttributeRef

Create a type attribute in context

§Details

Creates a string attribute within the current LLVM context or module.

This function simplifies the creation of a string attribute by wrapping the create_string_attribute method from AttributeRef. It creates a string attribute with the specified key and value within the context or module represented by self.

§Parameters

key: A string slice (&str) representing the key (kind) of the attribute.
value: A string slice (&str) representing the value of the attribute.

§Returns

Returns an AttributeRef representing the created string attribute.

Source

pub fn create_string_attribute(&self, key: &str, value: &str) -> AttributeRef

Create a string attribute in context

Source

pub fn get_type_by_name2(&self, name: &str) -> Option<TypeRef>

Obtain a Type from a context by its registered name.

§Details

Retrieves a type by its name within the current LLVM module or context.

This function wraps the LLVMGetTypeByName2 function from the LLVM core library. It searches for a type with the specified name within the context or module represented by self. If a type with the given name is found, it returns a TypeRef representing the type. Otherwise, it returns None.