Monkey Documentation

Class MegaPacket

A MegaPacket is a "chain stream" of Packet objects. More...

Extends:
  • SpecializedChainStream<Packet>
Constructors:
  • New ( Network:NetworkEngine, ID:PacketID, Destination:Client=null, ReleaseRights:Bool=true )
  • New ( Network:NetworkEngine, ReleaseRights:Bool=true )
Properties:
Methods:

Detailed Discussion

A MegaPacket is a "chain stream" of Packet objects. Basically, this means it can stitch together several Packet objects, and use them as makeshift buffers. As you write to a MegaPacket, it will automatically allocate Packet objects from its parent NetworkEngine. As it allocates, each Packet will receive a header, detailing its section meta-data. Once this is done, any data you write, or data that couldn't originally be written to the last Packet, will then be written to the newly aquired Packet object. The new packet then becomes the current Stream, and all operations will affect that packet. When you're finished writing to the MegaPacket, you can call Send with a NetworkEngine object, which will automatically handle the semantics of streaming to your destination. The MegaPacket you sent will then be handled internally, until it is finally relinquished when the operation completes. MegaPacket objects are usually sent in blocks, as described by the receiving end, meaning the Packet objects on the other end are queued up until all pieces are present. This message-staging is done using a MegaPacket object on the other end, managed by a NetworkEngine. When the message is finalized, the MegaPacket will be used as a Stream, and presented as the message-type used when it was sent from the original node.

Constructor Documentation

Method New ( Network:NetworkEngine, ID:PacketID, Destination:Client=null, ReleaseRights:Bool=true )

This constructs a MegaPacket for retrieval purposes. This does not start with a default Packet.

When using this constructor/purpose, please keep the ReleaseRights argument in mind when handling Packet objects.

MegaPackets allocated with this constructor must be "given up" (Ignored) upon integration with a NetworkEngine.

  • The Network argument will act as the parent to this MegaPacket, and will be queried for Packet handles.
  • The ID argument specifies the packet identifier associated with this exact MegaPacket. (Not to be confused with the IDs used by normal Packet objects)
  • The Destination argument specifies the sending node's Client handle.
  • The ReleaseRights argument specifies if this object has the right to call Release on the packets it allocates and/or holds.

Method New ( Network:NetworkEngine, ReleaseRights:Bool=true )

This constructs a MegaPacket for deployment purposes. This will generate a default packet, and mark it appropriately.

  • The Network argument will act as the parent to this MegaPacket, and will be queried for Packet handles.
Like the retrieval overload, the ReleaseRights argument is used to control releasing the packets this governs.

Property Documentation

Method CanTimeout : Bool () Property

This reports True if this MegaPacket is capable of timing-out. (IsRemoteHandle)

This property may not be overridden.

See also: TimeSinceLastUpdate, AutoUpdateTimeoutStatus, IsRemoteHandle

Method Destination : Client () Property

This is the destination associated with this MegaPacket This is assigned internally by a NetworkEngine when sending. This property has protected assignment-access.

Method ID : PacketID () Property

This acts as the unique identifier applied to this MegaPacket. Whenever this "packet" needs to be referenced over the network, this is used to do it. This is assigned internally by a NetworkEngine when sending. This property has protected assignment-access.

Method IsRemoteHandle : Bool () Property

If this object was created for retrieval purposes, this will return True.

This property may not be overridden.

This property has protected assignment-access.

Method Network : NetworkEngine () Property

This corresponds to the parent specified when creating this object. This property has protected assignment-access.

Method PacketsStaged : Int () Property

This describes the number of packet chunks/pieces we've asked for. This is assigned internally by a NetworkEngine when requesting chunks. This property has protected assignment-access.

Method TimeSinceLastUpdate : Duration () Property

If this object can time-out, then this will return the amount of time passed since the last call to AutoUpdateTimeoutStatus (Or similar).

This property may not be overridden.

See also: AutoUpdateTimeoutStatus

Method Type : MessageType () Property

This describes the type used to send this MegaPacket. This is assigned internally by a NetworkEngine when sending. This property has protected assignment-access.

Method Documentation

Method AutoUpdateTimeoutStatus : Void ()

This is used internally, and by Client objects when dealing with remote handles.

Basically, this updates an internal "time-point" used as a timer via TimeSinceLastUpdate.

If a remote handle idles for too long, it'll remove it, and abort the operation.

Only call this if you're sure what you're doing; framework extension.

This does not update the internal timer if this is not a "remote handle".

See also: IsRemoteHandle, CanTimeout, TimeSinceLastUpdate, UpdateWaitingMegaPackets

Method Close : Void ()

This overrides the super-class's 'Close' implementation.

This is akin to the Stream class's Close method.

This will release all internal packet handles if given closure rights.

See also: ForceClose, Reset

Method Construct : Void ( Network:NetworkEngine, ID:PacketID, Destination:Client=null )

This is used internally to construct a MegaPacket; used directly by systems like MegaPacketPools.

This is represented externally by the standard constructors.

This constructor is protected.

Method Construct : Void ( Network:NetworkEngine, Internal:Bool=false )

This is used internally to construct a MegaPacket; used directly by systems like MegaPacketPools.

This constructor is protected.

Method Extend : Packet ()

This is a (Mostly) internal routine, usage is not recommended unless you know what you're doing. This allocates a Packet using Network, then adds it internally. Please mark the beginning of the Packet this generates. (Unless handled through retrieval) This should be marked from this class, not the Packet returned.

Method ExtendAndMark : Bool ( MoveLink:Bool=true )

When calling this method, please be aware that the current position is used to mark the stream. This means you should only call this when at the end of a Packet thus, starting a new one with the proper markings. It's best to let this class handle this for you.

  • The MoveLink argument is considered "unsafe", and should only be used externally for debugging purposes.

Method ForceClose : Void ()

This will only force-close the chain if CanCloseStreams is enabled. (Privided by the parent class; basically "ReleaseRights")

Obviously, this will not re-use the packet-streams like Close would. In addition, this will not use the 100% proper control-path for packet-release.

See also: Close, Reset

Method MarkCurrentPacket : Void ( LinkNumber:Int, TotalLinks:Int )

This will write packet meta-data based on the input. See ExtendAndMark for details. Method MarkCurrentPacket:Void() This will use the current Link and LinkCount as inputs for the main implementation. See ExtendAndMark for details.

Method MarkPackets : Void ( Offset:Int=0 )

This marks every internal packet appropriately. (Called internally after writing has finished)

Method Reset : Void ()

This is just a wrapper for Close at the moment.

Method Write : Int ( Buffer:DataBuffer, Offset:Int, Count:Int )

This overrides the super-class's implementation. Basically, this handles over-stepping and of course, data transfer. This follows the Stream class's abstract Write method's documented behavior.