Ruby 3.4.5p51 (2025-07-16 revision 20cda200d3ce092571d0b5d342dadca69636cb0f)
|
Public APIs related to rb_mMarshal. More...
Go to the source code of this file.
Functions | |
VALUE | rb_marshal_dump (VALUE obj, VALUE port) |
Serialises the given object and all its referring objects, to write them down to the passed port. | |
VALUE | rb_marshal_load (VALUE port) |
Deserialises a previous output of rb_marshal_dump() into a network of objects. | |
void | rb_marshal_define_compat (VALUE newclass, VALUE oldclass, VALUE(*dumper)(VALUE), VALUE(*loader)(VALUE, VALUE)) |
Marshal format compatibility layer. |
Public APIs related to rb_mMarshal.
Definition in file marshal.h.
void rb_marshal_define_compat | ( | VALUE | newclass, |
VALUE | oldclass, | ||
VALUE(* | dumper )(VALUE), | ||
VALUE(* | loader )(VALUE, VALUE) ) |
Marshal format compatibility layer.
Over time, classes evolve, so that their internal data structure change drastically. For instance an instance of rb_cRange was made of RUBY_T_OBJECT in 1.x., but in 3.x it is a RUBY_T_STRUCT now. In order to keep binary compatibility, we "fake" the marshalled representation to stick to old types. This is the API to enable that manoeuvre. Here is how:
First, because you are going to keep backwards compatibility, you need to retain the old implementation of your class. Rename it, and keep the class somewhere (for instance rb_register_global_address() could help). Next create your new class. Do whatever you want.
Then, this is the key point. Create two new "bridge" functions that convert the structs back and forth:
Finally, connect all of them using this function.
[in] | newclass | The class that needs conversion. |
[in] | oldclass | Old implementation of newclass. |
[in] | dumper | Function that converts newclass to oldclass. |
[in] | loader | Function that converts oldclass to newclass. |
rb_eTypeError | `newclass` has no allocator. |
Serialises the given object and all its referring objects, to write them down to the passed port.
[in] | obj | Target object to dump. |
[out] | port | IO-like destination buffer. |
rb_eTypeError | `obj` cannot be dumped for some reason. |
rb_eRuntimeError | `obj` was tampered during dumping. |
rb_eArgError | Traversal too deep. |
Deserialises a previous output of rb_marshal_dump() into a network of objects.
[in,out] | port | Either IO or String. |
rb_eTypeError | `port` is in unexpected type. |
rb_eArgError | Contents of `port` is broken. |