tessl/pypi-pyfury

Blazingly fast multi-language serialization framework powered by JIT and zero-copy

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Type System and Reflection

Name: tessl/pypi-pyfury
Author: tessl

Apache Fury's type system provides advanced type handling with generic type support, reflection utilities, and cross-language type compatibility for efficient serialization.

Type Enumeration

Comprehensive type system for representing all supported data types.

public enum Type {
    // Primitive types
    BOOL,
    BYTE, SHORT, INT, LONG,
    FLOAT, DOUBLE,
    CHAR,
    
    // Object types
    STRING,
    ENUM,
    
    // Collection types
    ARRAY,
    LIST, SET, MAP,
    
    // Time types
    DATE, TIMESTAMP, INSTANT,
    LOCAL_DATE, LOCAL_TIME, LOCAL_DATE_TIME,
    
    // Special types
    NULL,
    NOT_NULL,
    REF,
    
    // Fury-specific types
    FURY_TYPE_TAG,
    FURY_SET,
    FURY_PRIMITIVE_BOOL_ARRAY,
    FURY_PRIMITIVE_SHORT_ARRAY,
    FURY_PRIMITIVE_INT_ARRAY,
    FURY_PRIMITIVE_LONG_ARRAY,
    FURY_PRIMITIVE_FLOAT_ARRAY,
    FURY_PRIMITIVE_DOUBLE_ARRAY,
    FURY_STRING_ARRAY,
    
    // Complex types
    OBJECT,
    SUBCLASS,
    FINAL_OBJECT_TYPE,
    
    // Cross-language types  
    TUPLE,
    ARROW_RECORD_BATCH,
    ARROW_TABLE;
    
    public short getId();
    public boolean isNullable();
    public boolean isPrimitive();
}

Type References

Generic type handling for preserving type information during serialization.

public class TypeRef<T> {
    // Type creation
    public static <T> TypeRef<T> of(Class<T> type);
    public static <T> TypeRef<T> of(Type type);
    
    // Type information
    public Type getType();
    public Class<T> getRawType();
    public java.lang.reflect.Type getGenericType();
    public TypeParameter<T>[] getTypeParameters();
    
    // Type checking
    public boolean isAssignableFrom(TypeRef<?> other);
    public boolean isGeneric();
    public boolean isArray();
    public boolean isCollection();
    public boolean isMap();
}

Type Parameters

Abstract base class for capturing generic type parameters at runtime.

public abstract class TypeParameter<X> {
    // Type parameter information
    public java.lang.reflect.Type getType();
    public Class<X> getRawType();
    
    // Usage: new TypeParameter<List<String>>() {}
}

Generics Utilities

Utilities for working with generic types and type parameters.

public class Generics {
    // Generic type operations
    public static java.lang.reflect.Type[] getTypeArguments(java.lang.reflect.Type type);
    public static Class<?> getRawType(java.lang.reflect.Type type);
    public static boolean isGeneric(java.lang.reflect.Type type);
    
    // Collection type handling
    public static java.lang.reflect.Type getCollectionElementType(java.lang.reflect.Type collectionType);
    public static java.lang.reflect.Type[] getMapKeyValueTypes(java.lang.reflect.Type mapType);
    
    // Type construction
    public static java.lang.reflect.ParameterizedType buildParameterizedType(Class<?> rawType, java.lang.reflect.Type... typeArguments);
    public static java.lang.reflect.GenericArrayType buildGenericArrayType(java.lang.reflect.Type componentType);
}

Type Utilities

General type manipulation and analysis utilities.

public class TypeUtils {
    // Type analysis
    public static boolean isPrimitive(Class<?> type);
    public static boolean isBoxedPrimitive(Class<?> type);
    public static boolean isFinal(Class<?> type);
    public static boolean isAbstract(Class<?> type);
    public static boolean isInterface(Class<?> type);
    public static boolean isEnum(Class<?> type);
    
    // Array utilities
    public static boolean isArray(Class<?> type);
    public static Class<?> getArrayComponentType(Class<?> type);
    public static int getArrayDimensions(Class<?> type);
    
    // Collection utilities
    public static boolean isCollection(Class<?> type);
    public static boolean isList(Class<?> type);
    public static boolean isSet(Class<?> type);
    public static boolean isMap(Class<?> type);
    
    // Type conversion
    public static Class<?> boxedType(Class<?> primitiveType);
    public static Class<?> unboxedType(Class<?> boxedType);
    
    // Class hierarchy
    public static List<Class<?>> getAllSuperTypes(Class<?> type);
    public static boolean isAssignableFrom(Class<?> superType, Class<?> subType);
}

Reflection Utilities

Advanced reflection operations optimized for serialization.

public class ReflectionUtils {
    // Field access
    public static Field[] getFields(Class<?> clazz);
    public static Field[] getDeclaredFields(Class<?> clazz);
    public static Field getField(Class<?> clazz, String fieldName);
    public static void setField(Field field, Object target, Object value);
    public static Object getField(Field field, Object target);
    
    // Constructor access
    public static <T> Constructor<T> getDefaultConstructor(Class<T> clazz);
    public static <T> T newInstance(Class<T> clazz);
    public static <T> T newInstance(Constructor<T> constructor, Object... args);
    
    // Method access
    public static Method getMethod(Class<?> clazz, String methodName, Class<?>... parameterTypes);
    public static Object invoke(Method method, Object target, Object... args);
    
    // Class loading
    public static Class<?> loadClass(String className);
    public static Class<?> loadClass(String className, ClassLoader classLoader);
    
    // Type introspection
    public static boolean hasDefaultConstructor(Class<?> clazz);
    public static boolean isInstantiable(Class<?> clazz);
    public static boolean isSerializable(Class<?> clazz);
    
    // Annotation utilities
    public static <A extends Annotation> A getAnnotation(Class<?> clazz, Class<A> annotationType);
    public static <A extends Annotation> A getAnnotation(Field field, Class<A> annotationType);
    public static boolean hasAnnotation(Class<?> clazz, Class<? extends Annotation> annotationType);
}

Field Access

High-performance field access abstractions.

public abstract class FieldAccessor {
    // Factory methods
    public static FieldAccessor createAccessor(Field field);
    public static FieldAccessor createUnsafeAccessor(Field field);
    
    // Field operations
    public abstract Object get(Object target);
    public abstract void set(Object target, Object value);
    
    // Primitive specializations
    public abstract boolean getBoolean(Object target);
    public abstract void setBoolean(Object target, boolean value);
    public abstract byte getByte(Object target);
    public abstract void setByte(Object target, byte value);
    public abstract int getInt(Object target);
    public abstract void setInt(Object target, int value);
    public abstract long getLong(Object target);
    public abstract void setLong(Object target, long value);
    public abstract float getFloat(Object target);
    public abstract void setFloat(Object target, float value);
    public abstract double getDouble(Object target);
    public abstract void setDouble(Object target, double value);
    
    // Field information
    public abstract Field getField();
    public abstract Class<?> getType();
    public abstract String getName();
}

Generic Type Handling

Advanced generic type operations for complex type scenarios.

public class GenericType {
    // Generic type construction
    public static GenericType of(java.lang.reflect.Type type);
    public static GenericType of(Class<?> rawType, GenericType... typeArguments);
    
    // Type information
    public Class<?> getRawType();
    public GenericType[] getTypeArguments();
    public boolean isGeneric();
    public boolean isWildcard();
    public boolean isBounded();
    
    // Type operations
    public GenericType getComponentType(); // For arrays
    public GenericType getKeyType(); // For maps
    public GenericType getValueType(); // For maps and collections
    
    // Type matching
    public boolean isAssignableFrom(GenericType other);
    public boolean matches(java.lang.reflect.Type type);
}

Usage Examples

Basic Type Operations

import org.apache.fury.type.Type;
import org.apache.fury.type.TypeRef;

// Working with Type enum
Type stringType = Type.STRING;
Type listType = Type.LIST;

// Creating type references
TypeRef<String> stringRef = TypeRef.of(String.class);
TypeRef<List<String>> listRef = new TypeRef<List<String>>() {};

// Type information
Class<String> rawType = stringRef.getRawType();
boolean isGeneric = listRef.isGeneric();

Generic Type Handling

import org.apache.fury.type.Generics;
import org.apache.fury.type.GenericType;

// Extract generic type information
java.lang.reflect.Type listStringType = new TypeParameter<List<String>>() {}.getType();
java.lang.reflect.Type elementType = Generics.getCollectionElementType(listStringType);

// Working with map types
java.lang.reflect.Type mapType = new TypeParameter<Map<String, Integer>>() {}.getType();
java.lang.reflect.Type[] keyValueTypes = Generics.getMapKeyValueTypes(mapType);
java.lang.reflect.Type keyType = keyValueTypes[0]; // String
java.lang.reflect.Type valueType = keyValueTypes[1]; // Integer

// Build parameterized types
java.lang.reflect.Type listIntType = Generics.buildParameterizedType(List.class, Integer.class);

Reflection Operations

import org.apache.fury.reflect.ReflectionUtils;
import org.apache.fury.reflect.FieldAccessor;

public class User {
    private String name;
    private int age;
    
    // constructors, getters, setters...
}

// Field access
Field nameField = ReflectionUtils.getField(User.class, "name");
FieldAccessor nameAccessor = FieldAccessor.createAccessor(nameField);

User user = new User();
nameAccessor.set(user, "Alice");
String name = (String) nameAccessor.get(user);

// High-performance field access
FieldAccessor ageAccessor = FieldAccessor.createUnsafeAccessor(
    ReflectionUtils.getField(User.class, "age"));
ageAccessor.setInt(user, 30);
int age = ageAccessor.getInt(user);

Type Analysis

import org.apache.fury.type.TypeUtils;

// Type checking
boolean isPrimitive = TypeUtils.isPrimitive(int.class);
boolean isCollection = TypeUtils.isCollection(List.class);
boolean isArray = TypeUtils.isArray(String[].class);

// Type conversion
Class<?> boxedInt = TypeUtils.boxedType(int.class); // Integer.class
Class<?> unboxedInteger = TypeUtils.unboxedType(Integer.class); // int.class

// Array analysis
Class<?> componentType = TypeUtils.getArrayComponentType(String[].class); // String.class
int dimensions = TypeUtils.getArrayDimensions(int[][][].class); // 3

Complex Generic Scenarios

// Nested generic types
TypeRef<Map<String, List<Integer>>> complexRef = new TypeRef<Map<String, List<Integer>>>() {};

// Extract nested type information
GenericType complexType = GenericType.of(complexRef.getGenericType());
GenericType keyType = complexType.getKeyType(); // String
GenericType valueType = complexType.getValueType(); // List<Integer>
GenericType listElementType = valueType.getComponentType(); // Integer

Runtime Type Construction

// Construct types at runtime
java.lang.reflect.Type runtimeListType = Generics.buildParameterizedType(
    List.class, 
    String.class);

GenericType genericType = GenericType.of(runtimeListType);

// Use with serialization
TypeRef<?> dynamicRef = TypeRef.of(genericType.getRawType());

Performance-Optimized Field Access

public class HighPerformanceSerializer {
    private final FieldAccessor[] fieldAccessors;
    
    public HighPerformanceSerializer(Class<?> clazz) {
        Field[] fields = ReflectionUtils.getFields(clazz);
        fieldAccessors = new FieldAccessor[fields.length];
        
        for (int i = 0; i < fields.length; i++) {
            // Use unsafe accessor for maximum performance
            fieldAccessors[i] = FieldAccessor.createUnsafeAccessor(fields[i]);
        }
    }
    
    public void serializeFields(Object obj, MemoryBuffer buffer) {
        for (FieldAccessor accessor : fieldAccessors) {
            Class<?> fieldType = accessor.getType();
            
            if (fieldType == int.class) {
                buffer.writeInt(accessor.getInt(obj));
            } else if (fieldType == String.class) {
                buffer.writeString((String) accessor.get(obj));
            }
            // ... handle other types
        }
    }
}

Performance Considerations

Type System Optimization

Type Caching: Fury caches type information to avoid repeated reflection
Unsafe Field Access: Used for maximum performance in hot paths
Generic Type Resolution: Resolved once and cached for subsequent use
Primitive Specialization: Optimized code paths for primitive types

Best Practices

Use TypeRef for Generic Types: Preserves full type information at runtime
Cache FieldAccessor Instances: Create once and reuse for multiple operations
Prefer Unsafe Accessors: For performance-critical serialization paths
Minimize Reflection: Use cached accessors rather than repeated reflection calls
Handle Type Erasure: Use TypeParameter pattern for capturing generic types

Memory Considerations

Type Metadata Caching: Reduces repeated type analysis overhead
Field Accessor Pooling: Reuse accessors to minimize object creation
Generic Type Optimization: Efficient representation of complex generic types

Install with Tessl CLI