Ruby
3.4.0dev (2024-11-22 revision 0989400a925cd201defdca9eb28eb87200b30785)
|
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. More... | |
VALUE | rb_marshal_load (VALUE port) |
Deserialises a previous output of rb_marshal_dump() into a network of objects. More... | |
void | rb_marshal_define_compat (VALUE newclass, VALUE oldclass, VALUE(*dumper)(VALUE), VALUE(*loader)(VALUE, VALUE)) |
Marshal format compatibility layer. More... | |
Public APIs related to rb_mMarshal.
RBIMPL
or rbimpl
are implementation details. Don't take them as canon. They could rapidly appear then vanish. The name (path) of this header file is also an implementation detail. Do not expect it to persist at the place it is now. Developers are free to move it anywhere anytime at will. __VA_ARGS__
is always available. We assume C99 for ruby itself but we don't assume languages of extension libraries. They could be written in C++98. Definition in file marshal.h.
void rb_marshal_define_compat | ( | VALUE | newclass, |
VALUE | oldclass, | ||
VALUE(*)(VALUE) | dumper, | ||
VALUE(*)(VALUE, VALUE) | loader | ||
) |
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. |
port
as-is. obj
is written to port
. port
is basically an IO but StringIO is also possible. 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. |
port
.