hunt.proton.engine.Sender source code

1 /*
2  * hunt-proton: AMQP Protocol library for D programming language.
3  *
4  * Copyright (C) 2018-2019 HuntLabs
5  *
6  * Website: https://www.huntlabs.net/
7  *
8  * Licensed under the Apache-2.0 License.
9  *
10  */
11 
12 module hunt.proton.engine.Sender;
13 
14 import hunt.proton.codec.ReadableBuffer;
15 import hunt.proton.engine.Link;
16 
17 /**
18  * Sender
19  *
20  */
21 interface Sender : Link
22 {
23 
24     /**
25      * indicates pending deliveries
26      *
27      * @param credits the number of pending deliveries
28      */
29     //TODO is this absolute or cumulative?
30     public void offer(int credits);
31 
32     /**
33      * Sends some data for the current delivery.  The application may call this method multiple
34      * times for the same delivery.
35      *
36      * @param bytes the byte array containing the data to be sent.
37      * @param offset the offset into the given array to start reading.
38      * @param length the number of bytes to read from the given byte array.
39      *
40      * @return the number of bytes accepted
41      *
42      * TODO Proton-j current copies all the bytes it has been given so the return value will always be
43      * length.  Should this be changed? How does Proton-c behave?   What should the application do if
44      * the number of bytes accepted is smaller than length.
45      */
46     public int send(byte[] bytes, int offset, int length);
47 
48     /**
49      * Sends some data for the current delivery. The application may call this method multiple
50      * times for the same delivery.
51      *
52      * @param buffer the buffer to read the data from.
53      *
54      * @return the number of bytes read from the provided buffer.
55      */
56     public int send(ReadableBuffer buffer);
57 
58     /**
59      * Sends data to the current delivery attempting not to copy the data unless a previous
60      * send has already added data to the Delivery in which case a copy may occur depending on
61      * the implementation.
62      * <p>
63      * Care should be taken when passing ReadableBuffer instances that wrapped pooled bytes
64      * as the send does not mean the data will be sent immediately when the transport is
65      * flushed so the pooled bytes could be held for longer than expected.
66      *
67      * @param buffer
68      *      An immutable ReadableBuffer that can be held until the next transport flush.
69      *
70      * @return the number of bytes read from the provided buffer.
71      */
72     public int sendNoCopy(ReadableBuffer buffer);
73 
74     /**
75      * Abort the current delivery.
76      *
77      * Note "pn_link_abort" is commented out in the .h
78      */
79     public void abort();
80 
81     /**
82      * {@inheritDoc}
83      *
84      * Informs the sender that all the bytes of the current {@link Delivery} have been written.
85      * The application must call this method in order for the delivery to be considered complete.
86      *
87      * @see #send(byte[], int, int)
88      *
89      * TODO fully state the rules regarding when you have to call this method, what happens if you don't call it
90      * before creating another delivery etc.
91      */
92     public bool advance();
93 
94 }