ic_c_protocol(3)

📦
version 5.2.2 · 2 versions
, in fedora 43, fedora 44

💖 ic_c_protocol — the IC C Protocol functions, bestie 💖

okay so this is the ic_c_protocol(3) page, and it lives in the C Library Functions section, and it's genuinely one of those deep-lore pages where if you're reading it you're either very brave or very deep in the IC sauce. either way, welcome, sit down, hydrate 🫶

✨ NAME ✨

ic_c_protocol — IC C Protocol Functions, aka the internal plumbing that makes generated C code talk to Erlang without you ever thinking about it (until today).

🌸 DESCRIPTION 🌸

This page lists some of the functions in the IC C runtime library that get used internally for the IC protocol. not all of them, just some — noted, no cap.

The listed functions are used internally by generated C client and server code. They're documented here for the advanced user who wants to replace the default protocol (Erlang distribution + gen_server) with his own protocol. for each set of client or server functions below with the prefix oe, the user has to implement his own set of functions — and the names of those functions are obtained by replacing the oe prefix with Prefix. the Prefix has to be set with the option {user_protocol, Prefix} at compile time. iconic DIY behaviour honestly 💅

here's the terminology, and it's literally baked into the function names so pay attention bestie:

  • a notification is a message sent from client to server, with no reply coming back — i.e. a oneway operation
  • a request is a message sent from client to server, and a reply message is sent back from the server to the client

and like, in order to actually understand how these functions work and what they do, the user must study their implementation in the IC C library (source file is ic.c), and also consider how they're used in the C code of ordinary generated client stubs or server skeletons. that's not optional, that's the assignment 📚

👑 CLIENT PROTOCOL FUNCTIONS 👑

The following functions are used internally by generated C client code. client-side girlies, this is your section 🎀

EXPORTS

  • int oe_prepare_notification_encoding(CORBA_Environment *env) — the result of this function is the beginning of a binary of in external format of the tuple {'$gen_cast', X} where X is not yet filled in. in generated client code this function is the first to be called in the encoding function for each oneway operation. first to the party, always 🎉
  • int oe_send_notification(CORBA_Environment *env)
  • int oe_send_notification_tmo(CORBA_Environment *env, unsigned int send_ms) — sends a client notification to a server according to the Erlang distribution + gen_server protocol. the send_ms parameter specified a timeout in milliseconds. yes, "specified", we're keeping it, it's part of the vibe ⏱️
  • int oe_prepare_request_encoding(CORBA_Environment *env) — the result of this function is the beginning of a binary in the external format of the tuple {'$gen_call', {Pid, Ref}, X} where X is not yet filled in. in generated client code this function is the first to be called in the encoding function for each twoway operation. twoway girlies rise 🦋
  • int oe_send_request_and_receive_reply(CORBA_Environment *env)
  • int oe_send_request_and_receive_reply_tmo(CORBA_Environment *env, unsigned int send_ms, unsigned int recv_ms) — sends a client request and receives the reply according to the Erlang distribution + gen_server protocol. this function calls the oe_prepare_reply_decoding function in order to obtain the gen_server reply. send_ms and recv_ms specify timeouts for send and receive, respectively, in milliseconds. two timeouts, two moods 💫
  • int oe_prepare_reply_decoding(CORBA_Environment *env) — decodes the binary version of the tuple {Ref, X}, where X is to be decoded later by the specific client decoding function. it's giving "we'll deal with X later" energy and honestly same 😭

🌈 SERVER PROTOCOL FUNCTIONS 🌈

The following functions are used internally by generated C server code. server side, you're up 💜

EXPORTS

  • int oe_prepare_request_decoding(CORBA_Environment *env) — decodes the binary version of the tuple {'$gen_cast', Op} (Op an atom), or the tuple {'$gen_cast', {Op, X}}, where Op is the operation name, and where X is to be decoded later by the specific operation decoding function; or

decodes the binary version of the tuple {'$gen_call', {Pid, Ref}, Op} (Op an atom), or the tuple {'$gen_call', {Pid, Ref}, {Op, X}}, where Op> is the operation name, and X is to be decode later by the specific operation decoding function.

bestie note: that Op> and that "to be decode" are verbatim from the original. not me fixing them. the source said it, I said it, we move on 🫶
  • int oe_prepare_reply_encoding(CORBA_Environment *env) — encodes the beginning of the binary version of the tuple {{Ref,X}, where X is to be filled in by the specific server encoding function.
another verbatim moment: the brace situation in {{Ref,X} is exactly as written. do not @ me, @ the original page 💀

🦋 SEE ALSO 🦋

go read those, they're the supporting cast and they ate ⭐

okay and that's the whole page!! this one came from Ericsson AB, and it's from ic 5.2.2, and the manual page itself is dated... well, it's the ic 5.2.2 era, ic_c_protocol(3), and that's the energy we're closing on. ty for reading my little manpage TED talk, mwah 💅💖✨

📦 where this page comes from