ltp::doc::pod3::ltp(3)

📦 version 3.2.1, in ubuntu jammy

💅 ltp — the LTP communications library, bestie edition ✨

okay so real talk: this is the manual page for ltp::doc::pod3::ltp(3), the man page all about the Licklider Transmission Protocol comms library. if you're here, you're tryna make apps talk over a long-latency link and you want the ✨reliable✨ girlie treatment. let's get into it 🫶

🌸 NAME 🌸

ltp — the Licklider Transmission Protocol (LTP) communications library 💖

✨ SYNOPSIS ✨

#include "ltp.h"

typedef enum
{
    LtpNoNotice = 0,
    LtpExportSessionStart,
    LtpXmitComplete,
    LtpExportSessionCanceled,
    LtpExportSessionComplete,
    LtpRecvGreenSegment,
    LtpRecvRedPart,
    LtpImportSessionCanceled
} LtpNoticeType;

[see description for available functions]

like yes that enum is a whole mood board of notice types, we'll get to them, don't worry 🎀

🦋 DESCRIPTION 🦋

so the ltp library hands you the functions you need to let your application software use LTP to send and receive info reliably over a long-latency link. it plays by the LTP spec as documented by the Delay-Tolerant Networking Research Group of the Internet Research Task Force. no cap, it's official 📜

LTP's notion of an engine ID is basically the Internet's notion of a host. and in ION, engine IDs are normally indistinguishable from node numbers — including the node numbers inside Bundle Protocol endpoint IDs that conform to the "ipn" scheme. iconic 🔥

LTP's notion of a client ID maps pretty much onto the Internet notion of a "protocol number" as used in the Internet Protocol. it's the thing that lets data from multiple applications — clients — get multiplexed over a single reliable link. heads up though: for ION operations we normally use LTP exclusively for transmitting Bundle Protocol data, and that's identified by client ID = 1. periodt 💅

🫶 int ltp_attach()

Attaches the application to LTP functionality on the local computer. Returns 0 on success, -1 on any error.

🙈 void ltp_detach()

Terminates all access to LTP functionality on the local computer. bye bestie 👋

👑 int ltp_engine_is_started()

Returns 1 if the local LTP engine has been started and not yet stopped, 0 otherwise.

💌 int ltp_send(uvast destinationEngineId, unsigned int clientId, Object clientServiceData, unsigned int redLength, LtpSessionId *sessionId)

Sends a client service data unit to the application that's waiting for data tagged with the indicated clientId, as received at the remote LTP engine identified by destinationEngineId.

clientServiceData must be a "zero-copy object" reference as returned by zco_create(). good news: LTP will privately make and destroy its own reference to the client service data object, so the application is free to destroy its reference at any time. no stress 🧚

redLength tells you the number of leading bytes of data in clientServiceData that are to be sent reliably — i.e., with selective retransmission in response to explicit or implicit negative acknowledgment as necessary. all the remaining bytes in clientServiceData get sent as "green" data, i.e., unreliably.

  • if redLength is zero, the entire client service data unit goes out unreliably.
  • if the entire client service data unit is to be sent reliably, redLength may simply be set to LTP_ALL_RED (i.e., -1). 💯

On success, the function populates *sessionId with the source engine ID and the "session number" assigned to transmission of this client service data unit, and returns zero. that session number is your lil receipt — you can use it to link future LTP processing events (like transmission cancellation, oop 😭) to the affected client service data. ltp_send() returns -1 on any error.

🔒 int ltp_open(unsigned int clientId)

Establishes the application's exclusive access to received service data units tagged with the indicated client service data ID. at any time, only a single application task is permitted to receive service data units for any single client service data ID. one girl, one client, iykyk 💅

Returns 0 on success, -1 on any error (e.g., the indicated client service is already being held open by some other application task). sorry babe, she's taken 🚫

📬 int ltp_get_notice(unsigned int clientId, LtpNoticeType *type, LtpSessionId *sessionId, unsigned char *reasonCode, unsigned char *endOfBlock, unsigned int *dataOffset, unsigned int *dataLength, Object *data)

Receives notices of LTP processing events pertaining to the flow of service data units tagged with the indicated client service ID. the nature of each event is indicated by *type. the extra params that characterize the event come back in *sessionId, *reasonCode, *endOfBlock, *dataOffset, *dataLength, and *data — as relevant. 🦋

the value returned in *data is always a zero-copy object; use the zco_* functions defined in "zco.h" to retrieve the content of that object.

when the notice is an LtpRecvGreenSegment, the ZCO returned in *data contains the content of a single LTP green segment. reassembly of the green part of some block from these segments is the responsibility of the application. you got this 🫡

when the notice is an LtpRecvRedPart, the ZCO returned in *data contains the red part of a possibly aggregated block. that means the ZCO's content may comprise multiple service data objects. extraction of individual service data objects from the aggregated block is — again — the responsibility of the application. a simple way to do this: prepend the length of the service data object to the object itself (using zco_prepend_header) before calling ltp_send, so the receiving application can alternate extraction of object lengths and objects from the delivered block's red part. little trick, big slay ✨

the cancellation of an export session may result in delivery of multiple LtpExportSessionCanceled notices — one for each service data unit in the export session's (potentially) aggregated block. the ZCO returned in *data for each such notice is a service data unit ZCO that had previously been passed to ltp_send().

ltp_get_notice() always blocks indefinitely until an LTP processing event is delivered. she will wait. forever. no timeout, no drama, just vibes 😭

Returns zero on success, -1 on any error.

⚡ void ltp_interrupt(unsigned int clientId)

Interrupts an ltp_get_notice() invocation. this function is designed to be called from a signal handler; for this purpose, clientId may need to be obtained from a static variable. noted bestie, keep it in a static 📌

🗑️ void ltp_release_data(Object data)

Releases the resources allocated to hold data, a client service data ZCO. clean up after yourself queen 🧹

🚪 void ltp_close(unsigned int clientId)

Terminates the application's exclusive access to received service data units tagged with the indicated client service data ID. closing the door behind you, iconic 🚪💖

🔍 SEE ALSO 🔍

and that's the whole page, bestie 💖 this one's from perl v5.24.1, dated 2016-07-07 — yes she's a vintage icon and she still ate 👑✨ go build something reliable, ily 🫶🌸

📦 where this page comes from