Demo
Demo

Knowledge base

PMTA knowledge base›Mechanism§ 7.5.1

Object lifetime in the C binding

allocate, initialise, free
Allocate, initialize, free

In the C binding, object creation is split into two calls — allocation and initialization — to distinguish running out of memory from other errors: …Alloc returns a null pointer if there is no memory, and initialization — PmtaConnConnectRemote, PmtaMsgInit, PmtaRcptInit — reports everything else.

When done, the object is freed with an …Free function; freeing a connection also closes it. A recipient is always freed — even after it is added to a message, otherwise memory leaks.

Hence the difference in size: there are more functions in the C section than methods in the C++ section, but the extra ones manage object lifetimes and query errors rather than adding capabilities.

The main trap is not freeing an object after an error. An error makes the object unusable, but it holds memory and the connection until …Free is called: a program that simply abandons such objects accumulates open connections.
What the Hub does. Not used: the Hub does not use the bindings.
Recommended values

Three steps for a connection and a message:

Step Connection Message
allocate PmtaConnAlloc PmtaMsgAlloc
initialize PmtaConnConnectRemote PmtaMsgInit
free PmtaConnFree PmtaMsgFree
The separation of allocation and initialization, freeing and closing the connection come from the manual (§ 7.5, § 7.5.1, § 7.5.6, § 7.5.9, § 7.5.29). The table is ours.
Example configuration
# a connection from allocation to freeing
PmtaConn conn = PmtaConnAlloc();
if (!PmtaConnConnectRemote(conn, "127.0.0.1", 25)) puts(PmtaConnGetLastError(conn));PmtaConnFree(conn);
PmtaConnFree is called on error too: it releases resources and closes the connection.
yellow — — directive names, blue — blocks. They are highlighted the same way in the text of the card.
Compatibility
PowerMTA 6.0
described in the manual of this version · platform: any
The vendor does not state the first version for every directive — there is no note here. The name also appears in the 5.0 edition of the manual.
⇄

Related entries

0 relations

Referenced from

C submission APIA related mechanism: they work together. § 7.5.1

How to check on the node
Check that the binding declarations are in place:
grep -n 'PmtaConnFree' /opt/pmta/api/include/submitter/PmtaConn.h
A function declaration in the header — the binding is installed.
In the Hub
Cost of a mistake
safe: a wrong value breaks nothing