ExceptionSink.h

/* -*- mode: c++; indent-tabs-mode: nil -*- */
/*
    ExceptionSink.h
 
    Qore Programming Language ExceptionSink class definition
 
    Copyright (C) 2003 - 2024 Qore Technologies, s.r.o.
 
    Permission is hereby granted, free of charge, to any person obtaining a
    copy of this software and associated documentation files (the "Software"),
    to deal in the Software without restriction, including without limitation
    the rights to use, copy, modify, merge, publish, distribute, sublicense,
    and/or sell copies of the Software, and to permit persons to whom the
    Software is furnished to do so, subject to the following conditions:
 
    The above copyright notice and this permission notice shall be included in
    all copies or substantial portions of the Software.
 
    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
    DEALINGS IN THE SOFTWARE.
 
    Note that the Qore library is released under a choice of three open-source
    licenses: MIT (as above), LGPL 2+, or GPL 2+; see README-LICENSE for more
    information.
*/
 
#ifndef _QORE_EXCEPTIONSINK_H
 
#define _QORE_EXCEPTIONSINK_H
 
#include <cstdarg>
#include <cstdio>
#include <string>
#include <vector>
 
// forward references
class QoreException;
class ExceptionSink;
class QoreXSinkException;
hashdecl QoreProgramLocation;
hashdecl QoreCallStack;
class AbstractStatement;
 
class ExceptionSink {
    friend hashdecl qore_es_private;
    friend QoreXSinkException;
 
public:
    DLLEXPORT ExceptionSink();
 
    DLLEXPORT ~ExceptionSink();
 
    DLLEXPORT void handleExceptions();
 
    DLLEXPORT void handleWarnings();
 
    DLLEXPORT bool isEvent() const;
 
    DLLEXPORT bool isThreadExit() const;
 
    DLLEXPORT bool isException() const;
 
 
    DLLEXPORT operator bool () const;
 
 
    DLLEXPORT AbstractQoreNode* raiseException(const char *err, const char *fmt, ...);
 
 
    DLLEXPORT AbstractQoreNode* raiseErrnoException(const char *err, int en, const char *fmt, ...);
 
 
    DLLEXPORT AbstractQoreNode* raiseErrnoException(const char *err, int en, QoreStringNode* desc);
 
 
    DLLEXPORT AbstractQoreNode* raiseExceptionArg(const char* err, QoreValue arg, const char* fmt, ...);
 
 
    DLLEXPORT AbstractQoreNode* raiseExceptionArg(const char* err, QoreValue arg, QoreStringNode* desc);
 
 
    DLLEXPORT AbstractQoreNode* raiseExceptionArg(const char* err, QoreValue arg, QoreStringNode* desc, const QoreCallStack& stack);
 
 
    DLLEXPORT AbstractQoreNode* raiseExceptionArg(const QoreProgramLocation& loc, const char* err, QoreValue arg, QoreStringNode* desc, const QoreCallStack& stack);
 
 
    DLLEXPORT AbstractQoreNode* raiseExceptionArg(const QoreProgramLocation& loc, const char* err, QoreValue arg, QoreStringNode* desc);
 
 
    DLLEXPORT AbstractQoreNode* raiseException(const char *err, QoreStringNode* desc);
 
 
    DLLEXPORT AbstractQoreNode* raiseException(QoreStringNode *err, QoreStringNode* desc);
 
 
    DLLEXPORT AbstractQoreNode* raiseException(QoreStringNode *err, QoreStringNode* desc, QoreValue arg);
 
 
    DLLEXPORT void raiseException(const QoreProgramLocation& loc, const char* err, QoreValue arg, QoreValue desc);
 
 
    DLLEXPORT void raiseException(const QoreProgramLocation& loc, const char* err, QoreValue arg, const char* fmt, ...);
 
    DLLEXPORT void raiseThreadExit();
 
    DLLEXPORT void assimilate(ExceptionSink *xs);
 
    DLLEXPORT void assimilate(ExceptionSink &xs);
 
 
    DLLEXPORT void outOfMemory();
 
    DLLEXPORT void clear();
 
    DLLEXPORT const QoreValue getExceptionErr();
 
    DLLEXPORT const QoreValue getExceptionDesc();
 
    DLLEXPORT const QoreValue getExceptionArg();
 
 
    DLLEXPORT int appendLastDescription(const char* fmt, ...);
 
    // Renames the "err" key of the top exception and prepends a string description to any desc value
    DLLEXPORT int renamePrependLastException(const char* err, const char* desc_fmt, ...);
 
    DLLEXPORT void markExternallyManaged();
 
 
    DLLEXPORT QoreHashNode* getExceptionInfo();
 
    DLLLOCAL void raiseException(QoreException* e);
    DLLLOCAL void raiseException(const QoreListNode* n);
    DLLLOCAL QoreException* catchException();
    DLLLOCAL QoreException* getException();
    DLLLOCAL void overrideLocation(const QoreProgramLocation& loc);
    DLLLOCAL void rethrow(QoreException* old);
 
    DLLLOCAL static void defaultExceptionHandler(QoreException* e);
    DLLLOCAL static void defaultWarningHandler(QoreException* e);
 
    DLLLOCAL static void outputExceptionLocation(const char* fns, int start_line, int end_line, const char* srcs,
        int offset, const char* langs, const char* types);
 
private:
    hashdecl qore_es_private* priv;
 
    ExceptionSink(const ExceptionSink&) = delete;
    ExceptionSink& operator=(const ExceptionSink&) = delete;
};
 
enum qore_call_t : signed char {
    CT_UNUSED     = -1,
    CT_USER       =  0,
    CT_BUILTIN    =  1,
    CT_NEWTHREAD  =  2,
    CT_RETHROW    =  3
};
 
 
hashdecl QoreSourceLocation {
    std::string label;     
    int start_line,        
        end_line;          
    std::string source;    
    unsigned offset = 0;   
    std::string code;      
    std::string lang;      
 
    DLLLOCAL QoreSourceLocation(const char* label, int start, int end, const char* code, const char* lang = "Qore") :
        label(label), start_line(start), end_line(end), code(code), lang(lang) {
    }
 
    DLLLOCAL QoreSourceLocation(const char* label, int start, int end, const char* source, unsigned offset,
        const char* code, const char* lang = "Qore") :
        label(label), start_line(start), end_line(end), source(source), offset(offset), code(code), lang(lang) {
    }
};
 
 
hashdecl QoreCallStackElement : public QoreSourceLocation {
    qore_call_t type;        
 
    DLLLOCAL QoreCallStackElement(qore_call_t type, const char* label, int start, int end, const char* code,
        const char* lang = "Qore") :
        QoreSourceLocation(label, start, end, code, lang), type(type) {
    }
 
    DLLLOCAL QoreCallStackElement(qore_call_t type, const char* label, int start, int end, const char* source,
        unsigned offset, const char* code, const char* lang = "Qore") :
        QoreSourceLocation(label, start, end, source, offset, code, lang), type(type) {
    }
};
 
typedef std::vector<QoreCallStackElement> callstack_vec_t;
 
 
hashdecl QoreCallStack : public callstack_vec_t {
    DLLEXPORT void add(qore_call_t type, const char* label, int start, int end, const char* code,
        const char* lang = "Qore");
 
    DLLEXPORT void add(qore_call_t type, const char* label, int start, int end, const char* source,
        unsigned offset, const char* code, const char* lang = "Qore");
};
 
static inline void alreadyDeleted(ExceptionSink *xsink, const char *cmeth) {
    xsink->raiseException("OBJECT-ALREADY-DELETED", "the method %s() cannot be executed because the object has already been deleted", cmeth);
}
 
static inline void makeAccessDeletedObjectException(ExceptionSink *xsink, const char *mem, const char *cname) {
    xsink->raiseException("OBJECT-ALREADY-DELETED", "attempt to access member '%s' of an already-deleted object of class '%s'", mem, cname);
}
 
static inline void makeAccessDeletedObjectException(ExceptionSink *xsink, const char *cname) {
    xsink->raiseException("OBJECT-ALREADY-DELETED", "attempt to access an already-deleted object of class '%s'", cname);
}
 
class QoreExternalProgramLocationWrapper {
public:
    DLLEXPORT QoreExternalProgramLocationWrapper();
 
    DLLEXPORT QoreExternalProgramLocationWrapper(const QoreExternalProgramLocationWrapper&);
 
    DLLEXPORT QoreExternalProgramLocationWrapper(QoreExternalProgramLocationWrapper&&);
 
    DLLEXPORT QoreExternalProgramLocationWrapper(const char* file, int start_line, int end_line,
        const char* source = nullptr, int offset = 0, const char* lang = nullptr);
 
    DLLEXPORT ~QoreExternalProgramLocationWrapper();
 
    DLLEXPORT void set(const char* file, int start_line, int end_line,
        const char* source = nullptr, int offset = 0, const char* lang = nullptr);
 
    DLLLOCAL const QoreProgramLocation& get() const {
        return *loc;
    }
 
    DLLLOCAL const std::string& getFile() const {
        return file_str;
    }
 
    DLLLOCAL const std::string& getSource() const {
        return source_str;
    }
 
    DLLLOCAL const std::string& getLanguage() const {
        return lang_str;
    }
 
    DLLEXPORT int getStartLine() const;
 
    DLLEXPORT int getEndLine() const;
 
private:
    // save strings for exceptions in case they are epheremal when this object is created
    std::string file_str;
    std::string source_str;
    std::string lang_str;
 
    // actual exception location
    QoreProgramLocation* loc;
};
 
 
class QoreStackLocation {
public:
    DLLLOCAL QoreStackLocation();
 
    DLLLOCAL QoreStackLocation(const QoreStackLocation&) = default;
 
    DLLLOCAL QoreStackLocation(QoreStackLocation&&) = default;
 
    DLLLOCAL virtual ~QoreStackLocation() = default;
 
    DLLLOCAL QoreStackLocation& operator=(const QoreStackLocation&) = default;
 
    DLLLOCAL QoreStackLocation& operator=(QoreStackLocation&&) = default;
 
 
    DLLLOCAL void setNext(const QoreStackLocation* next) {
        stack_next = next;
    }
 
    DLLLOCAL virtual const QoreStackLocation* getNext() const {
        return stack_next;
    }
 
    DLLLOCAL virtual QoreProgram* getProgram() const = 0;
 
    DLLLOCAL virtual const AbstractStatement* getStatement() const = 0;
 
    DLLLOCAL virtual const std::string& getCallName() const = 0;
 
    DLLLOCAL virtual qore_call_t getCallType() const = 0;
 
    DLLLOCAL virtual const QoreProgramLocation& getLocation() const = 0;
 
protected:
    const QoreStackLocation* stack_next = nullptr;
};
 
 
class QoreExternalStackLocation : public QoreStackLocation {
    friend class qore_external_runtime_stack_location_helper_priv;
public:
    DLLEXPORT QoreExternalStackLocation();
 
    DLLEXPORT QoreExternalStackLocation(const QoreExternalStackLocation&);
 
    DLLEXPORT QoreExternalStackLocation(QoreExternalStackLocation&&);
 
    DLLEXPORT virtual ~QoreExternalStackLocation();
 
    DLLLOCAL QoreExternalStackLocation& operator=(const QoreExternalStackLocation&) = delete;
 
    DLLLOCAL QoreExternalStackLocation& operator=(QoreExternalStackLocation&&) = delete;
 
    DLLEXPORT virtual QoreProgram* getProgram() const;
 
    DLLEXPORT virtual const AbstractStatement* getStatement() const;
 
private:
    class qore_external_stack_location_priv* priv;
};
 
 
class QoreExternalRuntimeStackLocationHelper : public QoreExternalStackLocation {
public:
    DLLEXPORT QoreExternalRuntimeStackLocationHelper();
 
    DLLEXPORT QoreExternalRuntimeStackLocationHelper(const QoreExternalRuntimeStackLocationHelper&);
 
    DLLEXPORT QoreExternalRuntimeStackLocationHelper(QoreExternalRuntimeStackLocationHelper&&);
 
    DLLEXPORT ~QoreExternalRuntimeStackLocationHelper();
 
    DLLLOCAL QoreExternalRuntimeStackLocationHelper& operator=(const QoreExternalRuntimeStackLocationHelper&) = delete;
 
    DLLLOCAL QoreExternalRuntimeStackLocationHelper& operator=(QoreExternalRuntimeStackLocationHelper&&) = delete;
 
private:
    class qore_external_runtime_stack_location_helper_priv* priv;
};
 
#endif