librpm 0.2.1

RPM Package Manager library binding with an idiomatic Rust API
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125

/*
 * Copyright (C) RustRPM Developers
 *
 * Licensed under the Mozilla Public License Version 2.0
 * Fedora-License-Identifier: MPLv2.0
 * SPDX-2.0-License-Identifier: MPL-2.0
 * SPDX-3.0-License-Identifier: MPL-2.0
 *
 * This is free software.
 * For more information on the license, see LICENSE.
 * For more information on free software, see <https://www.gnu.org/philosophy/free-sw.en.html>.
 *
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at <https://mozilla.org/MPL/2.0/>.
 */

//! Iterators for matches in the RPM database

use super::{header::Header, tag::DBIndexTag};
use std::{os::raw::c_void, ptr};
use streaming_iterator::StreamingIterator;

/// Iterator over the matches from a database query.
///
/// # Lifetime independence from `Db`
///
/// A `MatchIterator` does not borrow the `Db` or `TransactionSet` that
/// created it. This is safe because `rpmtsInitIterator` internally calls
/// `rpmtsLink` and `rpmdbLink`, giving the C-level iterator its own
/// reference-counted links to both the transaction set and the database.
/// The iterator walks a snapshot of the index taken at creation time.
/// When dropped, `rpmdbFreeIterator` releases those links.
///
/// # Header ownership
///
/// `rpmdbNextIterator` returns a pointer to an internal header that is
/// only valid until the next call. We use `StreamingIterator` to enforce
/// this, then the public `Iter` adapter clones each header (via
/// `Header::from_ptr` → `headerLink`) before it can be invalidated.
pub(crate) struct MatchIterator {
    /// Pointer to librpm's match iterator.
    ptr: *mut librpm_sys::rpmdbMatchIterator_s,

    /// Next item in the iterator
    next_item: Option<Header>,

    /// Have we already finished iterating?
    finished: bool,
}

impl MatchIterator {
    /// Create a new `MatchIterator` for the given transaction set's database,
    /// searching by the (optionally) given search key.
    pub(crate) fn new(
        ts: *mut librpm_sys::rpmts_s,
        tag: DBIndexTag,
        key_opt: Option<&str>,
    ) -> Self {
        let next_item = None;
        let finished = false;

        if let Some(key) = key_opt
            && !key.is_empty()
        {
            let ptr = unsafe {
                librpm_sys::rpmtsInitIterator(
                    ts,
                    tag as librpm_sys::rpm_tag_t,
                    key.as_ptr() as *const c_void,
                    key.len(),
                )
            };

            return Self {
                ptr,
                next_item,
                finished,
            };
        }

        let ptr = unsafe {
            librpm_sys::rpmtsInitIterator(ts, tag as librpm_sys::rpm_tag_t, ptr::null(), 0)
        };

        Self {
            ptr,
            next_item,
            finished,
        }
    }
}

/// Use a StreamingIterator to ensure that headers do not outlive `rpmdbNextIterator` calls.
impl StreamingIterator for MatchIterator {
    type Item = Header;

    fn advance(&mut self) {
        // Underlying rpmdb iterator has been consumed
        if self.finished {
            return;
        }

        let header_ptr = unsafe { librpm_sys::rpmdbNextIterator(self.ptr) };

        if header_ptr.is_null() {
            self.finished = true;
            self.next_item = None;
        } else {
            self.next_item = Some(unsafe { Header::from_ptr(header_ptr) })
        }
    }

    fn get(&self) -> Option<&Header> {
        self.next_item.as_ref()
    }
}

impl Drop for MatchIterator {
    fn drop(&mut self) {
        unsafe {
            librpm_sys::rpmdbFreeIterator(self.ptr);
        }
    }
}