pipe.hpp 6.94 KB
Newer Older
Martin Sustrik's avatar
Martin Sustrik committed
1
/*
2 3
    Copyright (c) 2007-2011 iMatix Corporation
    Copyright (c) 2007-2011 Other contributors as noted in the AUTHORS file
Martin Sustrik's avatar
Martin Sustrik committed
4 5 6 7

    This file is part of 0MQ.

    0MQ is free software; you can redistribute it and/or modify it under
8
    the terms of the GNU Lesser General Public License as published by
Martin Sustrik's avatar
Martin Sustrik committed
9 10 11 12 13 14
    the Free Software Foundation; either version 3 of the License, or
    (at your option) any later version.

    0MQ is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
15
    GNU Lesser General Public License for more details.
Martin Sustrik's avatar
Martin Sustrik committed
16

17
    You should have received a copy of the GNU Lesser General Public License
Martin Sustrik's avatar
Martin Sustrik committed
18 19 20
    along with this program.  If not, see <http://www.gnu.org/licenses/>.
*/

Martin Sustrik's avatar
Martin Sustrik committed
21 22
#ifndef __ZMQ_PIPE_HPP_INCLUDED__
#define __ZMQ_PIPE_HPP_INCLUDED__
Martin Sustrik's avatar
Martin Sustrik committed
23

24
#include "msg.hpp"
Martin Sustrik's avatar
Martin Sustrik committed
25 26
#include "ypipe.hpp"
#include "config.hpp"
Martin Sustrik's avatar
Martin Sustrik committed
27
#include "object.hpp"
28
#include "stdint.hpp"
29
#include "array.hpp"
Martin Sustrik's avatar
Martin Sustrik committed
30

Martin Sustrik's avatar
Martin Sustrik committed
31
namespace zmq
Martin Sustrik's avatar
Martin Sustrik committed
32 33
{

34 35 36
    //  Create a pipepair for bi-directional transfer of messages.
    //  First HWM is for messages passed from first pipe to the second pipe.
    //  Second HWM is for messages passed from second pipe to the first pipe.
37 38 39
    //  Delay specifies how the pipe behaves when the peer terminates. If true
    //  pipe receives all the pending messages before terminating, otherwise it
    //  terminates straight away.
40 41
    int pipepair (class object_t *parents_ [2], class pipe_t* pipes_ [2],
        int hwms_ [2], bool delays_ [2]);
42

43
    struct i_pipe_events
44
    {
45
        virtual ~i_pipe_events () {}
46

47 48
        virtual void read_activated (class pipe_t *pipe_) = 0;
        virtual void write_activated (class pipe_t *pipe_) = 0;
49
        virtual void hiccuped (class pipe_t *pipe_) = 0;
50
        virtual void terminated (class pipe_t *pipe_) = 0;
51 52
    };

53 54 55 56
    //  Note that pipe can be stored in three different arrays.
    //  The array of inbound pipes (1), the array of outbound pipes (2) and
    //  the generic array of pipes to deallocate (3).

57 58
    class pipe_t :
        public object_t,
59 60 61
        public array_item_t <1>,
        public array_item_t <2>,
        public array_item_t <3>
Martin Sustrik's avatar
Martin Sustrik committed
62
    {
63 64 65
        //  This allows pipepair to create pipe objects.
        friend int pipepair (class object_t *parents_ [2],
            class pipe_t* pipes_ [2], int hwms_ [2], bool delays_ [2]);
Martin Sustrik's avatar
Martin Sustrik committed
66

67
    public:
Martin Sustrik's avatar
Martin Sustrik committed
68

69 70
        //  Specifies the object to send events to.
        void set_event_sink (i_pipe_events *sink_);
Martin Sustrik's avatar
Martin Sustrik committed
71

72 73 74 75
        //  Pipe endpoint can store an opaque ID to be used by its clients.
        void set_pipe_id (uint32_t id_);
        uint32_t get_pipe_id ();

76 77 78
        //  Returns true if there is at least one message to read in the pipe.
        bool check_read ();

Martin Sustrik's avatar
Martin Sustrik committed
79
        //  Reads a message to the underlying pipe.
80
        bool read (msg_t *msg_);
Martin Sustrik's avatar
Martin Sustrik committed
81

82 83
        //  Checks whether messages can be written to the pipe. If writing
        //  the message would cause high watermark the function returns false.
84
        bool check_write (msg_t *msg_);
Martin Sustrik's avatar
Martin Sustrik committed
85 86 87

        //  Writes a message to the underlying pipe. Returns false if the
        //  message cannot be written because high watermark was reached.
88
        bool write (msg_t *msg_);
Martin Sustrik's avatar
Martin Sustrik committed
89

90
        //  Remove unfinished parts of the outbound message from the pipe.
91 92
        void rollback ();

Martin Sustrik's avatar
Martin Sustrik committed
93 94 95
        //  Flush the messages downsteam.
        void flush ();

96 97 98 99 100
        //  Temporaraily disconnects the inbound message stream and drops
        //  all the messages on the fly. Causes 'hiccuped' event to be generated
        //  in the peer.
        void hiccup ();

101 102
        //  Ask pipe to terminate. The termination will happen asynchronously
        //  and user will be notified about actual deallocation by 'terminated'
103 104 105
        //  event. If delay is true, the pending messages will be processed
        //  before actual shutdown.
        void terminate (bool delay_);
Martin Sustrik's avatar
Martin Sustrik committed
106

Martin Sustrik's avatar
Martin Sustrik committed
107 108
    private:

109 110 111
        //  Type of the underlying lock-free pipe.
        typedef ypipe_t <msg_t, message_pipe_granularity> upipe_t;

Martin Sustrik's avatar
Martin Sustrik committed
112
        //  Command handlers.
113 114
        void process_activate_read ();
        void process_activate_write (uint64_t msgs_read_);
115
        void process_hiccup (void *pipe_);
Martin Sustrik's avatar
Martin Sustrik committed
116
        void process_pipe_term ();
117 118
        void process_pipe_term_ack ();

119 120 121
        //  Handler for delimiter read from the pipe.
        void delimit ();

122 123 124 125
        //  Constructor is private. Pipe can only be created using
        //  pipepair function.
        pipe_t (object_t *parent_, upipe_t *inpipe_, upipe_t *outpipe_,
            int inhwm_, int outhwm_, bool delay_);
Martin Hurton's avatar
Martin Hurton committed
126

127 128 129
        //  Pipepair uses this function to let us know about
        //  the peer pipe object.
        void set_peer (pipe_t *pipe_);
Martin Hurton's avatar
Martin Hurton committed
130

131 132
        //  Destructor is private. Pipe objects destroy themselves.
        ~pipe_t ();
Martin Sustrik's avatar
Martin Sustrik committed
133

134 135 136
        //  Underlying pipes for both directions.
        upipe_t *inpipe;
        upipe_t *outpipe;
Martin Sustrik's avatar
Martin Sustrik committed
137

138 139 140 141 142
        //  Can the pipe be read from / written to?
        bool in_active;
        bool out_active;

        //  High watermark for the outbound pipe.
143
        int hwm;
Martin Sustrik's avatar
Martin Sustrik committed
144

145 146
        //  Low watermark for the inbound pipe.
        int lwm;
Martin Hurton's avatar
Martin Hurton committed
147

148 149
        //  Number of messages read and written so far.
        uint64_t msgs_read;
Martin Hurton's avatar
Martin Hurton committed
150 151
        uint64_t msgs_written;

152 153 154
        //  Last received peer's msgs_read. The actual number in the peer
        //  can be higher at the moment.
        uint64_t peers_msgs_read;
Martin Hurton's avatar
Martin Hurton committed
155

156 157 158 159 160 161
        //  The pipe object on the other side of the pipepair.
        pipe_t *peer;

        //  Sink to send events to.
        i_pipe_events *sink;

162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178
        //  State of the pipe endpoint. Active is common state before any
        //  termination begins. Delimited means that delimiter was read from
        //  pipe before term command was received. Pending means that term
        //  command was already received from the peer but there are still
        //  pending messages to read. Terminating means that all pending
        //  messages were already read and all we are waiting for is ack from
        //  the peer. Terminated means that 'terminate' was explicitly called
        //  by the user. Double_terminated means that user called 'terminate'
        //  and then we've got term command from the peer as well.
        enum {
            active,
            delimited,
            pending,
            terminating,
            terminated,
            double_terminated
        } state;
179 180 181 182 183 184

        //  If true, we receive all the pending inbound messages before
        //  terminating. If false, we terminate immediately when the peer
        //  asks us to.
        bool delay;

185 186 187
        //  Opaque ID. To be used by the clients, not the pipe itself.
        uint32_t pipe_id;

188 189 190 191 192 193 194 195 196
        //  Returns true if the message is delimiter; false otherwise.
        static bool is_delimiter (msg_t &msg_);

        //  Computes appropriate low watermark from the given high watermark.
        static int compute_lwm (int hwm_);

        //  Disable copying.
        pipe_t (const pipe_t&);
        const pipe_t &operator = (const pipe_t&);
Martin Sustrik's avatar
Martin Sustrik committed
197 198
    };

Martin Sustrik's avatar
Martin Sustrik committed
199 200 201
}

#endif