ec_message_builder

March 26, 2020 Contributors

Name

ec_message_builder — Convenience routine for building messages in a blocking fashion

Synopsis

#include "ec_message.h"

| io_object * **ec_message_builder** ( | mess, |   |
|   | size_hint); |   |

ec_message * <var class="pdparam">mess</var>;
size_t <var class="pdparam">size_hint</var>;

Description

Convenience routine for building messages in a blocking fashion.

Note

If you are constructing a message internally, this API will return an IO object that will hold the message as it is constructed. Each write to the object will incrementally parse that chunk into the message you have provided. If the message is larger than the large message threshold, it will internally be journalled to the spool in much the same way that large messages are received over SMTP. When the io_object is closed, it will finalize the parse and call ec_message_set_io_object() with the underlying storage for the message.

Parameters

mess

A pointer to an ec_message struct. For documentation of this data structure see “ec_message”

size_hint

An integer indicating the approximate size of the final message (in bytes) if known in advance.

Return Values

Returns the address of an io_object struct, which stores the current state of the message as it’s being constructed. For documentation of this data structure see “io_object”

Threading

It is legal to call this function in any thread but should not be called in the Scheduler thread.

Note

This function may induce IO blocking or otherwise block the caller. Blocking in the scheduler thread will lead to degraded performance and should be avoided at all costs. If your code is running in the IO subsystem, the core will have already taken steps to ensure that blocking is acceptable. Otherwise, you should look at using the thread pool API to run a job in the IO pool.