Source code
Revision control
Copy as Markdown
Other Tools
/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2; -*-
*/
/* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
#ifndef ctypes_CTypes_h
#define ctypes_CTypes_h
#include "mozilla/Sprintf.h"
#include "mozilla/Vector.h"
#include "ffi.h"
#include "prlink.h"
#include "ctypes/typedefs.h"
#include "gc/ZoneAllocator.h"
#include "js/AllocPolicy.h"
#include "js/GCHashTable.h"
#include "js/UniquePtr.h"
#include "js/Vector.h"
#include "vm/JSObject.h"
#include "vm/StringType.h"
namespace JS {
struct CTypesCallbacks;
} // namespace JS
namespace js {
namespace ctypes {
/*******************************************************************************
** Utility classes
*******************************************************************************/
// CTypes builds a number of strings. StringBuilder allows repeated appending
// with a single error check at the end. Only the Vector methods required for
// building the string are exposed.
template <class CharT, size_t N>
class StringBuilder {
Vector<CharT, N, SystemAllocPolicy> v;
// Have any (OOM) errors been encountered while constructing this string?
bool errored{false};
#ifdef DEBUG
// Have we finished building this string?
bool finished{false};
// Did we check for errors?
mutable bool checked{false};
#endif
public:
explicit operator bool() const {
#ifdef DEBUG
checked = true;
#endif
return !errored;
}
// Handle the result of modifying the string, by remembering the persistent
// errored status.
bool handle(bool result) {
MOZ_ASSERT(!finished);
if (!result) {
errored = true;
}
return result;
}
bool resize(size_t n) { return handle(v.resize(n)); }
CharT& operator[](size_t index) { return v[index]; }
const CharT& operator[](size_t index) const { return v[index]; }
size_t length() const { return v.length(); }
template <typename U>
[[nodiscard]] bool append(U&& u) {
return handle(v.append(u));
}
template <typename U>
[[nodiscard]] bool append(const U* begin, const U* end) {
return handle(v.append(begin, end));
}
template <typename U>
[[nodiscard]] bool append(const U* begin, size_t len) {
return handle(v.append(begin, len));
}
CharT* begin() {
MOZ_ASSERT(!finished);
return v.begin();
}
// finish() produces the results of the string building, and is required as
// the last thing before the string contents are used. The StringBuilder must
// be checked for errors before calling this, however.
Vector<CharT, N, SystemAllocPolicy>&& finish() {
MOZ_ASSERT(!errored);
MOZ_ASSERT(!finished);
MOZ_ASSERT(checked);
#ifdef DEBUG
finished = true;
#endif
return std::move(v);
}
};
// Note that these strings do not have any inline storage, because we use move
// constructors to pass the data around and inline storage would necessitate
// copying.
typedef StringBuilder<char16_t, 0> AutoString;
typedef StringBuilder<char, 0> AutoCString;
typedef Vector<char16_t, 0, SystemAllocPolicy> AutoStringChars;
typedef Vector<char, 0, SystemAllocPolicy> AutoCStringChars;
// Convenience functions to append, insert, and compare Strings.
template <class T, size_t N, size_t ArrayLength>
void AppendString(JSContext* cx, StringBuilder<T, N>& v,
const char (&array)[ArrayLength]) {
// Don't include the trailing '\0'.
size_t alen = ArrayLength - 1;
size_t vlen = v.length();
if (!v.resize(vlen + alen)) {
return;
}
for (size_t i = 0; i < alen; ++i) {
v[i + vlen] = array[i];
}
}
template <class T, size_t N>
void AppendChars(StringBuilder<T, N>& v, const char c, size_t count) {
size_t vlen = v.length();
if (!v.resize(vlen + count)) {
return;
}
for (size_t i = 0; i < count; ++i) {
v[i + vlen] = c;
}
}
template <class T, size_t N>
void AppendUInt(StringBuilder<T, N>& v, unsigned n) {
char array[16];
size_t alen = SprintfLiteral(array, "%u", n);
size_t vlen = v.length();
if (!v.resize(vlen + alen)) {
return;
}
for (size_t i = 0; i < alen; ++i) {
v[i + vlen] = array[i];
}
}
template <class T, size_t N, size_t M, class AP>
void AppendString(JSContext* cx, StringBuilder<T, N>& v,
mozilla::Vector<T, M, AP>& w) {
if (!v.append(w.begin(), w.length())) {
return;
}
}
template <size_t N>
void AppendString(JSContext* cx, StringBuilder<char16_t, N>& v, JSString* str) {
MOZ_ASSERT(str);
JSLinearString* linear = str->ensureLinear(cx);
if (!linear) {
return;
}
JS::AutoCheckCannotGC nogc;
if (linear->hasLatin1Chars()) {
if (!v.append(linear->latin1Chars(nogc), linear->length())) {
return;
}
} else {
if (!v.append(linear->twoByteChars(nogc), linear->length())) {
return;
}
}
}
template <size_t N>
void AppendString(JSContext* cx, StringBuilder<char, N>& v, JSString* str) {
MOZ_ASSERT(str);
size_t vlen = v.length();
size_t alen = str->length();
if (!v.resize(vlen + alen)) {
return;
}
JSLinearString* linear = str->ensureLinear(cx);
if (!linear) {
return;
}
JS::AutoCheckCannotGC nogc;
if (linear->hasLatin1Chars()) {
const Latin1Char* chars = linear->latin1Chars(nogc);
for (size_t i = 0; i < alen; ++i) {
v[i + vlen] = char(chars[i]);
}
} else {
const char16_t* chars = linear->twoByteChars(nogc);
for (size_t i = 0; i < alen; ++i) {
v[i + vlen] = char(chars[i]);
}
}
}
template <class T, size_t N, size_t ArrayLength>
void PrependString(JSContext* cx, StringBuilder<T, N>& v,
const char (&array)[ArrayLength]) {
// Don't include the trailing '\0'.
size_t alen = ArrayLength - 1;
size_t vlen = v.length();
if (!v.resize(vlen + alen)) {
return;
}
// Move vector data forward. This is safe since we've already resized.
memmove(v.begin() + alen, v.begin(), vlen * sizeof(T));
// Copy data to insert.
for (size_t i = 0; i < alen; ++i) {
v[i] = array[i];
}
}
template <size_t N>
void PrependString(JSContext* cx, StringBuilder<char16_t, N>& v,
JSString* str) {
MOZ_ASSERT(str);
size_t vlen = v.length();
size_t alen = str->length();
if (!v.resize(vlen + alen)) {
return;
}
JSLinearString* linear = str->ensureLinear(cx);
if (!linear) {
return;
}
// Move vector data forward. This is safe since we've already resized.
memmove(v.begin() + alen, v.begin(), vlen * sizeof(char16_t));
// Copy data to insert.
CopyChars(v.begin(), *linear);
}
[[nodiscard]] bool ReportErrorIfUnpairedSurrogatePresent(JSContext* cx,
JSLinearString* str);
[[nodiscard]] JSObject* GetThisObject(JSContext* cx, const CallArgs& args,
const char* msg);
/*******************************************************************************
** Function and struct API definitions
*******************************************************************************/
// for JS error reporting
enum ErrorNum {
#define MSG_DEF(name, count, exception, format) name,
#include "ctypes/ctypes.msg"
#undef MSG_DEF
CTYPESERR_LIMIT
};
/**
* ABI constants that specify the calling convention to use.
* ctypes.default_abi corresponds to the cdecl convention, and in almost all
* cases is the correct choice. ctypes.stdcall_abi is provided for calling
* stdcall functions on Win32, and implies stdcall symbol name decoration;
* ctypes.winapi_abi is just stdcall but without decoration.
*/
enum ABICode {
ABI_DEFAULT,
ABI_STDCALL,
ABI_THISCALL,
ABI_WINAPI,
INVALID_ABI
};
enum TypeCode {
TYPE_void_t,
#define DEFINE_TYPE(name, type, ffiType) TYPE_##name,
CTYPES_FOR_EACH_TYPE(DEFINE_TYPE)
#undef DEFINE_TYPE
TYPE_pointer,
TYPE_function,
TYPE_array,
TYPE_struct
};
// Descriptor of one field in a StructType. The name of the field is stored
// as the key to the hash entry.
struct FieldInfo {
HeapPtr<JSObject*> mType; // CType of the field
size_t mIndex; // index of the field in the struct (first is 0)
size_t mOffset; // offset of the field in the struct, in bytes
void trace(JSTracer* trc) { TraceEdge(trc, &mType, "fieldType"); }
};
struct UnbarrieredFieldInfo {
JSObject* mType; // CType of the field
size_t mIndex; // index of the field in the struct (first is 0)
size_t mOffset; // offset of the field in the struct, in bytes
};
static_assert(sizeof(UnbarrieredFieldInfo) == sizeof(FieldInfo),
"UnbarrieredFieldInfo should be the same as FieldInfo but with "
"unbarriered mType");
// Hash policy for FieldInfos.
struct FieldHashPolicy {
using Key = JSLinearString*;
using Lookup = Key;
static HashNumber hash(const Lookup& l) { return js::HashStringChars(l); }
static bool match(const Key& k, const Lookup& l) {
return js::EqualStrings(k, l);
}
};
using FieldInfoHash = GCHashMap<js::HeapPtr<JSLinearString*>, FieldInfo,
FieldHashPolicy, CellAllocPolicy>;
// Descriptor of ABI, return type, argument types, and variadicity for a
// FunctionType.
struct FunctionInfo {
explicit FunctionInfo(JS::Zone* zone) : mArgTypes(zone), mFFITypes(zone) {}
// Initialized in NewFunctionInfo when !mIsVariadic, but only later, in
// FunctionType::Call, when mIsVariadic. Not always consistent with
// mFFITypes, due to lazy initialization when mIsVariadic.
ffi_cif mCIF;
// Calling convention of the function. Convert to ffi_abi using GetABI
// and ObjectValue. Stored as a JSObject* for ease of tracing.
HeapPtr<JSObject*> mABI;
// The CType of the value returned by the function.
HeapPtr<JSObject*> mReturnType;
// A fixed array of known parameter types, excluding any variadic
// parameters (if mIsVariadic).
GCVector<HeapPtr<JSObject*>, 0, CellAllocPolicy> mArgTypes;
// A variable array of ffi_type*s corresponding to both known parameter
// types and dynamic (variadic) parameter types. Longer than mArgTypes
// only if mIsVariadic.
Vector<ffi_type*, 0, CellAllocPolicy> mFFITypes;
// Flag indicating whether the function behaves like a C function with
// ... as the final formal parameter.
bool mIsVariadic;
};
// Parameters necessary for invoking a JS function from a C closure.
struct ClosureInfo {
JSContext* cx;
HeapPtr<JSObject*> closureObj; // CClosure object
HeapPtr<JSObject*> typeObj; // FunctionType describing the C function
HeapPtr<JSObject*> thisObj; // 'this' object to use for the JS function call
HeapPtr<JSObject*> jsfnObj; // JS function
void* errResult; // Result that will be returned if the closure throws
ffi_closure* closure; // The C closure itself
// Anything conditionally freed in the destructor should be initialized to
// nullptr here.
explicit ClosureInfo(JSContext* context)
: cx(context), errResult(nullptr), closure(nullptr) {}
~ClosureInfo() {
if (closure) {
ffi_closure_free(closure);
}
js_free(errResult);
}
};
bool IsCTypesGlobal(HandleValue v);
bool IsCTypesGlobal(JSObject* obj);
const JS::CTypesCallbacks* GetCallbacks(JSObject* obj);
/*******************************************************************************
** JSClass reserved slot definitions
*******************************************************************************/
enum CTypesGlobalSlot {
SLOT_CALLBACKS = 0, // pointer to JS::CTypesCallbacks struct
SLOT_ERRNO = 1, // Value for latest |errno|
SLOT_LASTERROR =
2, // Value for latest |GetLastError|, used only with Windows
CTYPESGLOBAL_SLOTS
};
enum CABISlot {
SLOT_ABICODE = 0, // ABICode of the CABI object
CABI_SLOTS
};
enum CTypeProtoSlot {
SLOT_POINTERPROTO = 0, // ctypes.PointerType.prototype object
SLOT_ARRAYPROTO = 1, // ctypes.ArrayType.prototype object
SLOT_STRUCTPROTO = 2, // ctypes.StructType.prototype object
SLOT_FUNCTIONPROTO = 3, // ctypes.FunctionType.prototype object
SLOT_CDATAPROTO = 4, // ctypes.CData.prototype object
SLOT_POINTERDATAPROTO =
5, // common ancestor of all CData objects of PointerType
SLOT_ARRAYDATAPROTO = 6, // common ancestor of all CData objects of ArrayType
SLOT_STRUCTDATAPROTO =
7, // common ancestor of all CData objects of StructType
SLOT_FUNCTIONDATAPROTO =
8, // common ancestor of all CData objects of FunctionType
SLOT_INT64PROTO = 9, // ctypes.Int64.prototype object
SLOT_UINT64PROTO = 10, // ctypes.UInt64.prototype object
SLOT_CTYPES = 11, // ctypes object
SLOT_OURDATAPROTO = 12, // the data prototype corresponding to this object
CTYPEPROTO_SLOTS
};
enum CTypeSlot {
SLOT_PROTO = 0, // 'prototype' property of the CType object
SLOT_TYPECODE = 1, // TypeCode of the CType object
SLOT_FFITYPE = 2, // ffi_type representing the type
SLOT_NAME = 3, // name of the type
SLOT_SIZE = 4, // size of the type, in bytes
SLOT_ALIGN = 5, // alignment of the type, in bytes
SLOT_PTR = 6, // cached PointerType object for type.ptr
// Note that some of the slots below can overlap, since they're for
// mutually exclusive types.
SLOT_TARGET_T = 7, // (PointerTypes only) 'targetType' property
SLOT_ELEMENT_T = 7, // (ArrayTypes only) 'elementType' property
SLOT_LENGTH = 8, // (ArrayTypes only) 'length' property
SLOT_FIELDS = 7, // (StructTypes only) 'fields' property
SLOT_FIELDINFO = 8, // (StructTypes only) FieldInfoHash table
SLOT_FNINFO = 7, // (FunctionTypes only) FunctionInfo struct
SLOT_ARGS_T = 8, // (FunctionTypes only) 'argTypes' property (cached)
CTYPE_SLOTS
};
enum CDataSlot {
SLOT_CTYPE = 0, // CType object representing the underlying type
SLOT_REFERENT = 1, // JSObject this object must keep alive, if any
SLOT_DATA = 2, // pointer to a buffer containing the binary data
SLOT_OWNS = 3, // TrueValue() if this CData owns its own buffer
SLOT_FUNNAME = 4, // JSString representing the function name
CDATA_SLOTS
};
enum CClosureSlot {
SLOT_CLOSUREINFO = 0, // ClosureInfo struct
CCLOSURE_SLOTS
};
enum CDataFinalizerSlot {
// PrivateValue storing CDataFinalizer::Private* pointer or UndefinedValue.
SLOT_DATAFINALIZER_PRIVATE = 0,
// The type of the value (a CType JSObject).
// We hold it to permit ImplicitConvert and ToSource.
SLOT_DATAFINALIZER_VALTYPE = 1,
// The type of the function used at finalization (a CType JSObject).
// We hold it to permit |ToSource|.
SLOT_DATAFINALIZER_CODETYPE = 2,
CDATAFINALIZER_SLOTS
};
enum TypeCtorSlot {
SLOT_FN_CTORPROTO = 0 // ctypes.{Pointer,Array,Struct}Type.prototype
// JSFunction objects always get exactly two slots.
};
enum Int64Slot {
SLOT_INT64 = 0, // pointer to a 64-bit buffer containing the integer
INT64_SLOTS
};
enum Int64FunctionSlot {
SLOT_FN_INT64PROTO = 0 // ctypes.{Int64,UInt64}.prototype object
// JSFunction objects always get exactly two slots.
};
/*******************************************************************************
** Object API definitions
*******************************************************************************/
namespace CType {
JSObject* Create(JSContext* cx, HandleObject typeProto, HandleObject dataProto,
TypeCode type, JSString* name, HandleValue size,
HandleValue align, ffi_type* ffiType);
JSObject* DefineBuiltin(JSContext* cx, HandleObject ctypesObj,
const char* propName, JSObject* typeProto,
JSObject* dataProto, const char* name, TypeCode type,
HandleValue size, HandleValue align, ffi_type* ffiType);
bool IsCType(JSObject* obj);
bool IsCTypeProto(JSObject* obj);
TypeCode GetTypeCode(JSObject* typeObj);
bool TypesEqual(JSObject* t1, JSObject* t2);
size_t GetSize(JSObject* obj);
[[nodiscard]] bool GetSafeSize(JSObject* obj, size_t* result);
bool IsSizeDefined(JSObject* obj);
size_t GetAlignment(JSObject* obj);
ffi_type* GetFFIType(JSContext* cx, JSObject* obj);
JSString* GetName(JSContext* cx, HandleObject obj);
JSObject* GetProtoFromCtor(JSObject* obj, CTypeProtoSlot slot);
JSObject* GetProtoFromType(JSContext* cx, JSObject* obj, CTypeProtoSlot slot);
const JS::CTypesCallbacks* GetCallbacksFromType(JSObject* obj);
} // namespace CType
namespace PointerType {
JSObject* CreateInternal(JSContext* cx, HandleObject baseType);
JSObject* GetBaseType(JSObject* obj);
} // namespace PointerType
using UniquePtrFFIType = UniquePtr<ffi_type>;
namespace ArrayType {
JSObject* CreateInternal(JSContext* cx, HandleObject baseType, size_t length,
bool lengthDefined);
JSObject* GetBaseType(JSObject* obj);
size_t GetLength(JSObject* obj);
[[nodiscard]] bool GetSafeLength(JSObject* obj, size_t* result);
UniquePtrFFIType BuildFFIType(JSContext* cx, JSObject* obj);
} // namespace ArrayType
namespace StructType {
[[nodiscard]] bool DefineInternal(JSContext* cx, JSObject* typeObj,
JSObject* fieldsObj);
const FieldInfoHash* GetFieldInfo(JSObject* obj);
const FieldInfo* LookupField(JSContext* cx, JSObject* obj,
JSLinearString* name);
JSObject* BuildFieldsArray(JSContext* cx, JSObject* obj);
UniquePtrFFIType BuildFFIType(JSContext* cx, JSObject* obj);
} // namespace StructType
namespace FunctionType {
JSObject* CreateInternal(JSContext* cx, HandleValue abi, HandleValue rtype,
const HandleValueArray& args);
JSObject* ConstructWithObject(JSContext* cx, JSObject* typeObj,
JSObject* refObj, PRFuncPtr fnptr,
JSObject* result);
FunctionInfo* GetFunctionInfo(JSObject* obj);
void BuildSymbolName(JSContext* cx, JSString* name, JSObject* typeObj,
AutoCString& result);
} // namespace FunctionType
namespace CClosure {
JSObject* Create(JSContext* cx, HandleObject typeObj, HandleObject fnObj,
HandleObject thisObj, HandleValue errVal, PRFuncPtr* fnptr);
} // namespace CClosure
namespace CData {
JSObject* Create(JSContext* cx, HandleObject typeObj, HandleObject refObj,
void* data, bool ownResult);
JSObject* GetCType(JSObject* dataObj);
void* GetData(JSObject* dataObj);
bool IsCData(JSObject* obj);
bool IsCDataMaybeUnwrap(MutableHandleObject obj);
bool IsCData(HandleValue v);
bool IsCDataProto(JSObject* obj);
// Attached by JSAPI as the function 'ctypes.cast'
[[nodiscard]] bool Cast(JSContext* cx, unsigned argc, Value* vp);
// Attached by JSAPI as the function 'ctypes.getRuntime'
[[nodiscard]] bool GetRuntime(JSContext* cx, unsigned argc, Value* vp);
} // namespace CData
namespace Int64 {
bool IsInt64(JSObject* obj);
} // namespace Int64
namespace UInt64 {
bool IsUInt64(JSObject* obj);
} // namespace UInt64
} // namespace ctypes
} // namespace js
#endif /* ctypes_CTypes_h */