[−][src]Function dqcsim::bindings::dqcs_scfg_log_callback

#[no_mangle]pub extern "C" fn dqcs_scfg_log_callback(
    scfg: dqcs_handle_t, 
    verbosity: dqcs_loglevel_t, 
    callback: Option<extern "C" fn(user_data: *mut c_void, message: *const c_char, logger: *const c_char, level: dqcs_loglevel_t, module: *const c_char, file: *const c_char, line: u32, time_s: u64, time_ns: u32, pid: u32, tid: u64)>, 
    user_free: Option<extern "C" fn(user_data: *mut c_void)>, 
    user_data: *mut c_void
) -> dqcs_return_t

Configures DQCsim to also output its log messages to callback function.

verbosity specifies the minimum importance of a message required for the callback to be called.

callback is the callback function to install. It is always called with the user_data pointer to make calling stuff like class member functions or closures possible. The user_free function, if non-null, will be called when the callback is uninstalled in any way. If callback is null, any current callback is uninstalled instead. For consistency, if user_free is non-null while callback is null, user_free is called immediately, under the assumption that the caller has allocated resources unbeknownst that the callback it's trying to install is null.

NOTE: both callback and user_free may be called from a thread spawned by the simulator. Calling any API calls from the callback is therefore undefined behavior!

The callback takes the following arguments:

void*: user defined data.
const char*: log message string, excluding metadata.
const char*: name assigned to the logger that was used to produce the message (= "dqcsim" or a plugin name).
dqcs_loglevel_t: the verbosity level that the message was logged with.
const char*: string representing the source of the log message, or NULL when no source is known.
const char*: string containing the filename of the source that generated the message, or NULL when no source is known.
uint32_t: line number within the aforementioned file, or 0 if not known.
uint64_t: Time in seconds since the Unix epoch.
uint32_t: Additional time in nanoseconds since the aforementioned.
uint32_t: PID of the generating process.
uint64_t: TID of the generating thread.

If an internal log record is particularly malformed and cannot be coerced into the above (nul bytes in the strings, invalid timestamp, whatever) the message is silently ignored.

The primary use of this callback is to pipe DQCsim's messages to an external logging framework. When you do this, you probably also want to call dqcs_scfg_stderr_verbosity_set(handle, DQCS_LOG_OFF) to prevent DQCsim from writing the messages to stderr itself.