socket.h

Go to the documentation of this file.

 
 
#pragma once
// This header file is auto-generated!
// Do not make changes to this file or they will be overwritten.
// clang-format off
#include <cx/obj.h>
#include <cx/struct.h>
#include <cx/net/queue.h>
#include <cx/net/filter.h>
#include <cx/net/net_shared.h>
#include <cx/buffer/bufchain.h>
#include <cx/buffer/bufring.h>
#include <cx/thread.h>
 
CX_C_BEGIN
 
typedef struct NetFlow NetFlow;
typedef struct NetFlow_WeakRef NetFlow_WeakRef;
typedef struct NetSocket NetSocket;
typedef struct NetSocket_WeakRef NetSocket_WeakRef;
saDeclarePtr(NetSocket);
saDeclarePtr(NetSocket_WeakRef);
#define _sti_NetSocket _sti_object
#define SType_NetSocket NetSocket*
#define STStorageType_NetSocket NetSocket*
#define STypeArg_NetSocket(type, val) stgeneric(object, (ObjInst*)objInstCheckClass(NetSocket, val))
#define STypeArgPtr_NetSocket(type, val) (stgeneric*)objInstCheckClassPtr(NetSocket, val)
#define STypeCheckedArg_NetSocket(type, val)    stType(type), stArg(type, val)
#define STypeCheckedPtrArg_NetSocket(type, val) stType(type), stArgPtr(type, val)
 
 
typedef bool (*socketRecvCB)(NetSocket* sock, NetMessage* msg, void* ctx);
 
typedef struct NetSocket_ClassIf {
    ObjIface* _implements;
    ObjIface* _parent;
    size_t _size;
 
    size_t (*recv)(_In_ void* self, _Out_ uint8* buf, size_t bufsz, _Out_opt_ NetAddr* src, flags_t flags);
    bool (*recvMsgs)(_In_ void* self, socketRecvCB cb, _In_opt_ void* ctx);
    bool (*send)(_In_ void* self, _In_ const uint8* data, size_t len, _In_opt_ const NetAddr* dest, flags_t flags);
    bool (*connect)(_In_ void* self, _In_ strref host, uint16 port);
    bool (*bind)(_In_ void* self, const NetAddr* addr);
    // backlog 0 means use a platform-specific default
    bool (*listen)(_In_ void* self, int backlog);
    bool (*close)(_In_ void* self);
} NetSocket_ClassIf;
extern NetSocket_ClassIf NetSocket_ClassIf_tmpl;
 
typedef struct NetSocket {
    union {
        NetSocket_ClassIf* _;
        void* _is_NetSocket;
        void* _is_ObjInst;
    };
    ObjClassInfo* _clsinfo;
    atomic(uintptr) _ref;
    atomic(ptr) _weakref;
 
    Weak(NetQueue)* queue;        
    NetSocketType type;        
    NetSockHandle handle;
    atomic(uint32) state;        
    atomic(bool) canSend;        
    // An accepted socket the application has not been handed yet. While it is set, no worker
    // delivers anything of this socket's to the application: NET_Accepted travels on the
    // *listener's* flow, so nothing orders it against events on the accepted socket's own flows,
    // and a QUIC connection has streams opening on flows of their own the moment its handshake
    // finishes. Without this, the NET_FlowOpen for a peer's first stream can be delivered before
    // the application has seen the connection, and it goes to the handlers the socket inherited
    // from the listener rather than the ones the application installs when it does. Cleared once
    // NET_Accepted has been delivered, which is also when those flows are put back on the
    // runqueue.
    //     // A QUIC connection's control flow still runs while this is set, because it is what answers
    // the handshake that raises the accept -- but only as far as its first application-facing
    // message, which waits like everything else. See drainFlow().
    atomic(uint32) awaitingAccept;
    NetAddr local;
    NetAddr remote;        
    uint32 mru;        
    bool recvInfo;
    NetSocketBufs bufs;
    Mutex recvLock;        
    Mutex sendLock;        
    size_t sendHigh;
    size_t sendLow;
    size_t sendQueued;
    bool sendBlocked;
    bool sendPending;
    NetHandlers* handlers;
    void* handlerCtx;        
    Weak(ObjInst)* handlerWeak;
    RWLock handlerLock;        
    hashtable flows;
    RWLock flowLock;        
    NetFlow* flow;
    // Hook that takes arriving datagrams instead of the flow table, or NULL for the normal path.
    // Installed by cxquic on the UDP endpoint socket behind a QUIC connection or listener; nothing
    // else installs one. See NetDatagramRouteFn and _setRoute().
    //     // Written only under flowLock, which the ingest path holds just long enough to copy the hook
    // and turn the weak context into a reference. `route` alone is also read without it, as a hint
    // of whether to take the lock at all.
    NetDatagramRouteFn route;
    Weak(ObjInst)* routeCtx;
    // Who installed the hook, compared and never dereferenced -- the weak reference above cannot
    // answer that once its object is being destroyed, which is one of the times it is asked.
    void* routeOwner;
    sa_NetFilter filters;
    NetConnectPref connectPref;
    sa_NetAddr connQueue;
    int32 connectIdx;        
    NetTimerId connectTimer;
    atomic(uint32) connectGen;
    Mutex connectLock;
} NetSocket;
extern ObjClassInfo NetSocket_clsinfo;
#define NetSocket(inst) objInstCheckClass(NetSocket, inst)
#define NetSocketNone ((NetSocket*)NULL)
 
typedef struct NetSocket_WeakRef {
    union {
        ObjInst* _inst;
        void* _is_NetSocket_WeakRef;
        void* _is_ObjInst_WeakRef;
    };
    atomic(uintptr) _ref;
    RWLock _lock;
} NetSocket_WeakRef;
#define NetSocket_WeakRef(inst) objWeakRefCheckClass(NetSocket, inst)
 
bool NetSocket_sendEx(_In_ NetSocket* self, _In_ const uint8* data, size_t len, _In_ const NetAddr* dest, _In_opt_ const NetPktInfo* info, flags_t flags);
#define netsocketSendEx(self, data, len, dest, info, flags) NetSocket_sendEx(NetSocket(self), data, len, dest, info, flags)
 
bool NetSocket_setRecvInfo(_In_ NetSocket* self, bool enable);
#define netsocketSetRecvInfo(self, enable) NetSocket_setRecvInfo(NetSocket(self), enable)
 
bool NetSocket_setDontFragment(_In_ NetSocket* self, bool enable);
#define netsocketSetDontFragment(self, enable) NetSocket_setDontFragment(NetSocket(self), enable)
 
void NetSocket_setHandlers(_In_ NetSocket* self, _In_opt_ const NetHandlers* handlers, _In_opt_ void* ctx);
#define netsocketSetHandlers(self, handlers, ctx) NetSocket_setHandlers(NetSocket(self), handlers, ctx)
 
void NetSocket_setHandlersObj(_In_ NetSocket* self, _In_opt_ const NetHandlers* handlers, _In_opt_ ObjInst* ctx);
#define netsocketSetHandlersObj(self, handlers, ctx) NetSocket_setHandlersObj(NetSocket(self), handlers, ObjInst(ctx))
 
bool NetSocket_addFilter(_In_ NetSocket* self, _In_ NetFilter* filter);
#define netsocketAddFilter(self, filter) NetSocket_addFilter(NetSocket(self), NetFilter(filter))
 
void NetSocket_removeFilters(_In_ NetSocket* self);
#define netsocketRemoveFilters(self) NetSocket_removeFilters(NetSocket(self))
 
bool NetSocket__wantWrite(_In_ NetSocket* self);
// bool netsocket_wantWrite(NetSocket* self);
//
// -----------------------------------------------------------------------------------------
// PRIVATE IMPLEMENTATION DETAILS
//     // Everything below this point is internal plumbing between the net module's own translation
// units and the platform backends. It is not a stable API and carries no compatibility
// promise -- signatures and semantics change whenever the implementation needs them to.
// -----------------------------------------------------------------------------------------
// Send path (dataplane.c)
//     // The send logic is backend-independent and lives on the base socket; only the syscall differs
// and it is hidden behind netSockSendv/netSockSendTo. A readiness backend watches sockets that
// have queued data for write-readiness and flushes them from its ingest loop.
// True when the socket has outbound data queued and should be watched for write-readiness. A
// hint read without the send lock -- a stale value costs at most one empty flush or one poll
// cycle.
#define netsocket_wantWrite(self) NetSocket__wantWrite(NetSocket(self))
 
void NetSocket__flushSend(_In_ NetSocket* self, _In_opt_ NetQueue* q);
// void netsocket_flushSend(NetSocket* self, NetQueue* q);
//
// Flush as much queued outbound data as the OS will currently accept, updating canSend and
// firing NET_SendReady on the flow when the backlog drains back below the low watermark.
// Called by the backend on write-readiness; `q` may be NULL if the socket has no queue
// (nothing to deliver on).
#define netsocket_flushSend(self, q) NetSocket__flushSend(NetSocket(self), NetQueue(q))
 
void NetSocket__sendError(_In_ NetSocket* self, _In_opt_ NetQueue* q, NetErrorCode err, _In_ NetAddr* peer);
// void netsocket_sendError(NetSocket* self, NetQueue* q, NetErrorCode err, NetAddr* peer);
//
// Report a fatal error from the async send path: the call that queued the bytes already
// returned success, so an event is the only way the application can hear about the loss.
// Delivers NET_Error through the affected flow like everything else -- on a worker, ordered. A
// stream's byte stream is broken by bytes vanishing from the middle of it, so its flow is
// closed behind the event: NET_Error lands first carrying the code, and NET_FlowClosed
// (NCR_Error) follows. A datagram error cost only the one datagram, so the peer's flow (`peer`
// is the failed datagram's destination; ignored for streams) hears NET_Error and stays open --
// and since sending alone never creates a flow, an error for a peer that has no flow has
// nobody to tell and is dropped. Do not call with sendLock held.
#define netsocket_sendError(self, q, err, peer) NetSocket__sendError(NetSocket(self), NetQueue(q), err, peer)
 
void NetSocket__connectResult(_In_ NetSocket* self, NetErrorCode err);
// void netsocket_connectResult(NetSocket* self, NetErrorCode err);
//
// Connect (connect.c)
// Report the outcome of the in-flight connect attempt and advance the state machine: on
// success the socket goes NS_Connected and its NET_Connection event is queued; on failure the
// next resolved address is tried, or a failing NET_Connection is delivered when the list is
// exhausted. Claims the per-attempt transition by cancelling connectTimer, so the backend
// completion and the attempt's own timeout cannot both advance it. Safe to call from either;
// the loser is a no-op.
#define netsocket_connectResult(self, err) NetSocket__connectResult(NetSocket(self), err)
 
bool NetSocket__readinessConnect(_In_ NetSocket* self, _Inout_ NetQueue* q, _In_ const NetAddr* addr);
// bool netsocket_readinessConnect(NetSocket* self, NetQueue* q, const NetAddr* addr);
//
// Shared readiness-backend connectBegin body: reset the handle to the address's family, issue
// a non-blocking connect(), and drive the immediate outcome through netsocket_connectResult().
// A pending connect is left for the select loop to complete on writability/except. Returns
// true once the attempt has been initiated (the state machine has been advanced or is now
// pending).
#define netsocket_readinessConnect(self, q, addr) NetSocket__readinessConnect(NetSocket(self), NetQueue(q), addr)
 
void NetSocket__connectCancel(_In_ NetSocket* self);
// void netsocket_connectCancel(NetSocket* self);
//
// Abort an in-flight connect when the socket is being closed. Claims the current attempt the
// same way the backend completion and the timeout do; if won, drops the connect's resources
// without starting a new attempt or delivering an event. A no-op if there is no armed attempt
// -- either nothing is connecting, or the completion/timeout already finished it, or the
// connect is still resolving (that window is handled in the resolver callback, which checks
// NS_Closed).
#define netsocket_connectCancel(self) NetSocket__connectCancel(NetSocket(self))
 
void NetSocket__accepted(_In_ NetSocket* self, _Inout_ NetSocket* newSock, _In_opt_ const NetAddr* peer);
// void netsocket_accepted(NetSocket* self, NetSocket* newSock, const NetAddr* peer);
//
// Accept and listen (socket.c)
// Deliver a freshly accepted connection. `newSock` arrives owning one reference (the platform
// factory's), which this call takes: with NQ_AutoAccept the socket is first added to the
// listener's queue (which acquires its own reference), then an NMSG_Accept carrying the socket
// is queued on the listener's flow so NET_Accepted runs on a worker, ordered. If the listener
// has no queue or flow to deliver on, the socket is dropped (released, closing its handle).
// Called by both backends once they have pulled a connection off the backlog and wrapped it in
// a platform NetSocket. `peer` is the remote address, or NULL if it could not be determined.
#define netsocket_accepted(self, newSock, peer) NetSocket__accepted(NetSocket(self), NetSocket(newSock), peer)
 
void NetSocket__listenArm(_In_ NetSocket* self);
// void netsocket_listenArm(NetSocket* self);
//
// Kick the backend into servicing a socket that has just started listening. Resolves the
// socket's queue and calls its acceptArm hook (select wakes its loop to read-watch the
// listener; IOCP posts the initial AcceptEx batch). A no-op if the socket is not yet on a
// queue -- the backend's addSocket picks up an already-listening socket instead. Called by the
// platform listen() once the socket is in NS_Listening.
#define netsocket_listenArm(self) NetSocket__listenArm(NetSocket(self))
 
void NetSocket__setRoute(_In_ NetSocket* self, _In_ NetDatagramRouteFn fn, _In_ ObjInst* ctx);
// void netsocket_setRoute(NetSocket* self, NetDatagramRouteFn fn, ObjInst* ctx);
//
// Install a datagram route hook, replacing whatever was installed before. `ctx` is held weakly
// and passed to the hook as a reference for the length of each call, so a datagram that
// arrives after it is gone is dropped instead of routed to freed memory.
#define netsocket_setRoute(self, fn, ctx) NetSocket__setRoute(NetSocket(self), fn, ObjInst(ctx))
 
bool NetSocket__clearRoute(_In_ NetSocket* self, _In_ ObjInst* owner);
// bool netsocket_clearRoute(NetSocket* self, ObjInst* owner);
//
// Remove the route hook, but only if `owner` is what installed it. Returns true if it did.
// Safe to call from `owner`'s destroy, when it can no longer be referenced.
#define netsocket_clearRoute(self, owner) NetSocket__clearRoute(NetSocket(self), ObjInst(owner))
 
void NetSocket__dropFlow(_In_ NetSocket* self, _Inout_ NetFlow* flow);
// void netsocket_dropFlow(NetSocket* self, NetFlow* flow);
//
// Flow table (flow.c)
// Remove a flow from this socket's table, releasing the socket's reference. Called once the
// terminal event has been delivered.
#define netsocket_dropFlow(self, flow) NetSocket__dropFlow(NetSocket(self), NetFlow(flow))
 
void NetSocket__closeFlows(_In_ NetSocket* self, NetCloseReason reason);
// void netsocket_closeFlows(NetSocket* self, NetCloseReason reason);
//
// Close every flow on this socket with the given reason.
#define netsocket_closeFlows(self, reason) NetSocket__closeFlows(NetSocket(self), reason)
 
#define netsocketRecv(self, buf, bufsz, src, flags) (self)->_->recv(NetSocket(self), buf, bufsz, src, flags)
#define netsocketRecvMsgs(self, cb, ctx) (self)->_->recvMsgs(NetSocket(self), cb, ctx)
#define netsocketSend(self, data, len, dest, flags) (self)->_->send(NetSocket(self), data, len, dest, flags)
#define netsocketConnect(self, host, port) (self)->_->connect(NetSocket(self), host, port)
// bool netsocketBind(NetSocket* self, const NetAddr* addr);
#define netsocketBind(self, addr) (self)->_->bind(NetSocket(self), addr)
// bool netsocketListen(NetSocket* self, int backlog);
//
// backlog 0 means use a platform-specific default
#define netsocketListen(self, backlog) (self)->_->listen(NetSocket(self), backlog)
#define netsocketClose(self) (self)->_->close(NetSocket(self))
 
CX_C_END