CommCalls.h

Go to the documentation of this file.

/*
 * Copyright (C) 1996-2025 The Squid Software Foundation and contributors
 *
 * Squid software is distributed under GPLv2+ license and includes
 * contributions from numerous individuals and organizations.
 * Please see the COPYING and CONTRIBUTORS files for details.
 */
 
#ifndef SQUID_SRC_COMMCALLS_H
#define SQUID_SRC_COMMCALLS_H
 
#include "base/AsyncCall.h"
#include "base/AsyncJobCalls.h"
#include "comm/Flag.h"
#include "comm/forward.h"
#include "MasterXaction.h"
 
/* CommCalls implement AsyncCall interface for comm_* callbacks.
 * The classes cover two call dialer kinds:
 *     - A C-style call using a function pointer (deprecated);
 *     - A C++-style call to an AsyncJob child.
 * and several comm_* callback kinds:
 *     - accept (IOACB)
 *     - connect (CNCB)
 *     - I/O (IOCB)
 *     - timeout (CTCB)
 *     - close (CLCB)
 */
 
class CommAcceptCbParams;
typedef void IOACB(const CommAcceptCbParams &params);
 
typedef void CNCB(const Comm::ConnectionPointer &conn, Comm::Flag status, int xerrno, void *data);
typedef void IOCB(const Comm::ConnectionPointer &conn, char *, size_t size, Comm::Flag flag, int xerrno, void *data);
 
class CommTimeoutCbParams;
typedef void CTCB(const CommTimeoutCbParams &params);
 
class CommCloseCbParams;
typedef void CLCB(const CommCloseCbParams &params);
 
/*
 * TODO: When there are no function-pointer-based callbacks left, all
 * this complexity can be removed. Jobs that need comm services will just
 * implement CommReader, CommWriter, etc. interfaces and receive calls
 * using general (not comm-specific) AsyncCall code. For now, we have to
 * allow the caller to create a callback that comm can modify to set
 * parameters, which is not trivial when the caller type/kind is not
 * known to comm and there are many kinds of parameters.
 */
 
/* Comm*CbParams classes below handle callback parameters */
 
// Maintains parameters common to all comm callbacks
class CommCommonCbParams
{
public:
    CommCommonCbParams(void *aData);
    CommCommonCbParams(const CommCommonCbParams &params);
    ~CommCommonCbParams();
 
    // not virtual because callers know dialer type
    bool syncWithComm() { return true; }
 
    void print(std::ostream &os) const;
 
public:
    void *data; // cbdata-protected
 
    Comm::ConnectionPointer conn;
 
    Comm::Flag flag;  
    int xerrno;      
 
    int fd; 
private:
    // should not be needed and not yet implemented
    CommCommonCbParams &operator =(const CommCommonCbParams &params);
};
 
// accept parameters
class CommAcceptCbParams: public CommCommonCbParams
{
public:
    CommAcceptCbParams(void *aData);
 
    void print(std::ostream &os) const;
 
    AnyP::PortCfgPointer port;
};
 
// connect parameters
class CommConnectCbParams: public CommCommonCbParams
{
public:
    CommConnectCbParams(void *aData);
 
    bool syncWithComm(); // see CommCommonCbParams::syncWithComm
};
 
// read/write (I/O) parameters
class CommIoCbParams: public CommCommonCbParams
{
public:
    CommIoCbParams(void *aData);
 
    void print(std::ostream &os) const;
    bool syncWithComm(); // see CommCommonCbParams::syncWithComm
 
public:
    char *buf;
    size_t size;
};
 
// close parameters
class CommCloseCbParams: public CommCommonCbParams
{
public:
    CommCloseCbParams(void *aData);
};
 
class CommTimeoutCbParams: public  CommCommonCbParams
{
public:
    CommTimeoutCbParams(void *aData);
};
 
// Interface to expose comm callback parameters of all comm dialers.
// GetCommParams() uses this interface to access comm parameters.
template <class Params_>
class CommDialerParamsT
{
public:
    typedef Params_ Params;
    CommDialerParamsT(const Params &io): params(io) {}
 
public:
    Params params;
};
 
// Get comm params of an async comm call
template <class Params>
Params &GetCommParams(AsyncCall::Pointer &call)
{
    typedef CommDialerParamsT<Params> DialerParams;
    DialerParams *dp = dynamic_cast<DialerParams*>(call->getDialer());
    assert(dp);
    return dp->params;
}
 
// All job dialers with comm parameters are merged into one since they
// all have exactly one callback argument and differ in Params type only
template <class C, class Params_>
class CommCbMemFunT: public JobDialer<C>, public CommDialerParamsT<Params_>
{
public:
    typedef Params_ Params;
    typedef void (C::*Method)(const Params &io);
 
    CommCbMemFunT(const CbcPointer<C> &aJob, Method aMeth): JobDialer<C>(aJob),
        CommDialerParamsT<Params_>(aJob->toCbdata()),
        method(aMeth) {}
 
    bool canDial(AsyncCall &c) override {
        return JobDialer<C>::canDial(c) &&
               this->params.syncWithComm();
    }
 
    void print(std::ostream &os) const override {
        os << '(';
        this->params.print(os);
        os << ')';
    }
 
public:
    Method method;
 
protected:
    void doDial() override { ((&(*this->job))->*method)(this->params); }
};
 
// accept (IOACB) dialer
class CommAcceptCbPtrFun: public CallDialer,
    public CommDialerParamsT<CommAcceptCbParams>
{
public:
    typedef CommAcceptCbParams Params;
    typedef RefCount<CommAcceptCbPtrFun> Pointer;
 
    CommAcceptCbPtrFun(IOACB *aHandler, const CommAcceptCbParams &aParams);
    CommAcceptCbPtrFun(const CommAcceptCbPtrFun &o);
 
    void dial();
 
    void print(std::ostream &os) const override;
 
public:
    IOACB *handler;
};
 
// connect (CNCB) dialer
class CommConnectCbPtrFun: public CallDialer,
    public CommDialerParamsT<CommConnectCbParams>
{
public:
    typedef CommConnectCbParams Params;
 
    CommConnectCbPtrFun(CNCB *aHandler, const Params &aParams);
    void dial();
 
    void print(std::ostream &os) const override;
 
public:
    CNCB *handler;
};
 
// read/write (IOCB) dialer
class CommIoCbPtrFun: public CallDialer,
    public CommDialerParamsT<CommIoCbParams>
{
public:
    typedef CommIoCbParams Params;
 
    CommIoCbPtrFun(IOCB *aHandler, const Params &aParams);
    void dial();
 
    void print(std::ostream &os) const override;
 
public:
    IOCB *handler;
};
 
// close (CLCB) dialer
class CommCloseCbPtrFun: public CallDialer,
    public CommDialerParamsT<CommCloseCbParams>
{
public:
    typedef CommCloseCbParams Params;
 
    CommCloseCbPtrFun(CLCB *aHandler, const Params &aParams);
    void dial();
 
    void print(std::ostream &os) const override;
 
public:
    CLCB *handler;
};
 
class CommTimeoutCbPtrFun:public CallDialer,
    public CommDialerParamsT<CommTimeoutCbParams>
{
public:
    typedef CommTimeoutCbParams Params;
 
    CommTimeoutCbPtrFun(CTCB *aHandler, const Params &aParams);
    void dial();
 
    void print(std::ostream &os) const override;
 
public:
    CTCB *handler;
};
 
// AsyncCall to comm handlers implemented as global functions.
// The dialer is one of the Comm*CbPtrFunT above
// TODO: Get rid of this class by moving canFire() to canDial() method
// of dialers.
template <class Dialer>
class CommCbFunPtrCallT: public AsyncCall
{
public:
    typedef RefCount<CommCbFunPtrCallT<Dialer> > Pointer;
    typedef typename Dialer::Params Params;
 
    inline CommCbFunPtrCallT(int debugSection, int debugLevel,
                             const char *callName, const Dialer &aDialer);
 
    inline CommCbFunPtrCallT(const CommCbFunPtrCallT &o) :
        AsyncCall(o.debugSection, o.debugLevel, o.name),
        dialer(o.dialer) {}
 
    ~CommCbFunPtrCallT() override {}
 
    CallDialer* getDialer() override { return &dialer; }
 
public:
    Dialer dialer;
 
protected:
    inline bool canFire() override;
    inline void fire() override;
 
private:
    CommCbFunPtrCallT & operator=(const CommCbFunPtrCallT &); // not defined. not permitted.
};
 
// Conveninece wrapper: It is often easier to call a templated function than
// to create a templated class.
template <class Dialer>
inline
CommCbFunPtrCallT<Dialer> *commCbCall(int debugSection, int debugLevel,
                                      const char *callName, const Dialer &dialer)
{
    return new CommCbFunPtrCallT<Dialer>(debugSection, debugLevel, callName,
                                         dialer);
}
 
/* inlined implementation of templated methods */
 
/* CommCbFunPtrCallT */
 
template <class Dialer>
CommCbFunPtrCallT<Dialer>::CommCbFunPtrCallT(int aDebugSection, int aDebugLevel,
        const char *callName, const Dialer &aDialer):
    AsyncCall(aDebugSection, aDebugLevel, callName),
    dialer(aDialer)
{
}
 
template <class Dialer>
bool
CommCbFunPtrCallT<Dialer>::canFire()
{
    if (!AsyncCall::canFire())
        return false;
 
    if (!cbdataReferenceValid(dialer.params.data))
        return cancel("callee gone");
 
    if (!dialer.params.syncWithComm())
        return cancel("out of sync w/comm");
 
    if (!dialer.handler)
        return cancel("no callback requested");
 
    return true;
}
 
template <class Dialer>
void
CommCbFunPtrCallT<Dialer>::fire()
{
    dialer.dial();
}
 
#endif /* SQUID_SRC_COMMCALLS_H */