1
0
Fork 0
mirror of https://github.com/ruby/ruby.git synced 2022-11-09 12:17:21 -05:00

document marshal_dump and marshal_load

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@28017 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
This commit is contained in:
drbrain 2010-05-26 02:50:58 +00:00
parent 259c3a1c4c
commit dd8d4f0075
2 changed files with 78 additions and 9 deletions

View file

@ -1,3 +1,7 @@
Wed May 26 11:50:09 2010 Eric Hodel <drbrain@segment7.net>
* marshal.c (Init_marshal): document marshal_dump and marshal_load.
Wed May 26 10:35:37 2010 Nobuyoshi Nakada <nobu@ruby-lang.org>
* configure.in (rb_cv_large_fd_select): needed on mingw, even

View file

@ -892,8 +892,10 @@ clear_dump_arg(struct dump_arg *arg)
*
* Marshal can't dump following objects:
* * anonymous Class/Module.
* * objects which related to its system (ex: Dir, File::Stat, IO, File, Socket and so on)
* * an instance of MatchData, Data, Method, UnboundMethod, Proc, Thread, ThreadGroup, Continuation
* * objects which related to its system (ex: Dir, File::Stat, IO, File, Socket
* and so on)
* * an instance of MatchData, Data, Method, UnboundMethod, Proc, Thread,
* ThreadGroup, Continuation
* * objects which defines singleton methods
*/
static VALUE
@ -1820,6 +1822,7 @@ marshal_load(int argc, VALUE *argv)
* byte stream, allowing them to be stored outside the currently
* active script. This data may subsequently be read and the original
* objects reconstituted.
*
* Marshaled data has major and minor version numbers stored along
* with the object information. In normal use, marshaling can only
* load data written with the same major version number and an equal
@ -1837,16 +1840,78 @@ marshal_load(int argc, VALUE *argv)
* Some objects cannot be dumped: if the objects to be dumped include
* bindings, procedure or method objects, instances of class IO, or
* singleton objects, a TypeError will be raised.
*
* If your class has special serialization needs (for example, if you
* want to serialize in some specific format), or if it contains
* objects that would otherwise not be serializable, you can implement
* your own serialization strategy by defining two methods, _dump and
* _load:
* The instance method _dump should return a String object containing
* all the information necessary to reconstitute objects of this class
* and all referenced objects up to a maximum depth given as an integer
* parameter (a value of -1 implies that you should disable depth checking).
* The class method _load should take a String and return an object of this class.
* your own serialization strategy.
*
* There are two methods of doing this, your object can define either
* marshal_dump and marshal_load or _dump and _load. marshal_dump will take
* precedence over _dump if both are defined. marshal_dump may result in
* smaller Marshal strings.
*
* == marshal_dump and marshal_load
*
* When dumping an object the method marshal_dump will be called.
* marshal_dump must return a result containing the information necessary for
* marshal_load to reconstitute the object. The result can be any object.
*
* When loading an object dumped using marshal_dump the object is first
* allocated then marshal_load is called with the result from marshal_dump.
* marshal_load must recreate the object from the information in the result.
*
* Example:
*
* class MyObj
* def initialize name, version, data
* @name = name
* @version = version
* @data = data
* end
*
* def marshal_dump
* [@name, @version]
* end
*
* def marshal_load array
* @name, @version = array
* end
* end
*
* == _dump and _load
*
* Use _dump and _load when you need to allocate the object you're restoring
* yourself.
*
* When dumping an object the instance method _dump is called with an Integer
* which indicates the maximum depth of objects to dump (a value of -1 implies
* that you should disable depth checking). _dump must return a String
* containing the information necessary to reconstitute the object.
*
* The class method _load should take a String and use it to return an object
* of the same class.
*
* Example:
*
* class MyObj
* def initialize name, version, data
* @name = name
* @version = version
* @data = data
* end
*
* def _dump level
* [@name, @version].join ':'
* end
*
* def self._load args
* new(*args.split(':'))
* end
* end
*
* Since Marhsal.dump outputs a string you can have _dump return a Marshal
* string which is Marshal.loaded in _load for complex objects.
*/
void
Init_marshal(void)